{
    "openapi": "3.0.3",
    "info": {
        "title": "Stocky API",
        "version": "5.7",
        "description": "REST API reference for Stocky — inventory, POS, sales, purchases, HRM, accounting, online store, client portal and industry modules. Auto-generated from the Stocky source code; human-written descriptions are merged from docs/overrides.",
        "x-generated-at": "2026-09-06T15:47:42+00:00",
        "x-source-generated-at": "2026-09-06T03:45:05+00:00"
    },
    "servers": [
        {
            "url": "{baseUrl}",
            "description": "Your Stocky installation",
            "variables": {
                "baseUrl": {
                    "default": "https://your-stocky-domain.com"
                }
            }
        }
    ],
    "x-sections": [
        "Authentication & Public",
        "Dashboard & Reports",
        "Catalog",
        "Inventory",
        "Sales",
        "Purchases",
        "Point of Sale",
        "People",
        "Finance",
        "Human Resources",
        "Work Management",
        "Service Jobs",
        "Assets",
        "Commissions",
        "Online Store (Admin)",
        "Storefront",
        "Client Portal",
        "Mobile App",
        "Marketing",
        "Integrations",
        "Industry Modules",
        "System & Settings"
    ],
    "tags": [
        {
            "name": "Authentication",
            "description": "How staff users obtain and use an API token. Stocky's admin API is protected by Laravel Passport: you exchange an email and password for a personal access token, then send it on every call either as a `Authorization: Bearer <token>` header or in the `Stocky_token` cookie that the login endpoint sets. Tokens are long-lived but a per-session inactivity timeout (System Settings → Security) and the \"log out device\" feature can revoke them; a revoked or expired token returns `401`. Users whose account is inactive (`statut = 0`) cannot log in.",
            "x-section": "Authentication & Public"
        },
        {
            "name": "Health & Utilities",
            "description": "Small unauthenticated endpoints used by the admin SPA, the installer and monitoring: reachability probes, the logo for the login page, and the translation catalogue.",
            "x-section": "Authentication & Public"
        },
        {
            "name": "Public PDF & Print",
            "description": "Document renderers reachable without a bearer token so they can be opened in a new browser tab or an `<iframe>` straight from the UI (the browser sends the `Stocky_token` cookie, but the routes themselves sit outside the `auth:api` group). `*_pdf` endpoints stream a generated PDF (`Content-Disposition: attachment`); `*_print_html` endpoints return the same template as raw HTML for the print-popup flow (`window.print()`). Amounts are shown in the document's own currency (stored base-currency values × the document rate). Batch/expiry columns appear when pharmacy mode is on. The service-job renderers additionally check the `view` permission on service jobs.",
            "x-section": "Authentication & Public"
        },
        {
            "name": "Batch Reports",
            "description": "Pharmacy / batch-tracked stock reports: the batch register and the per-batch movement history. Return `supported: false` with an empty payload when the batch tables have not been migrated. Permission `batch_reports` (falls back to `stock_report`).",
            "x-section": "Dashboard & Reports"
        },
        {
            "name": "Dashboard",
            "description": "Aggregated data behind the admin home screen, the Today's-summary drawer, the real-time sales counter, the 3D sales dashboard and the pending-work widget. Every endpoint applies the caller's warehouse assignments (`is_all_warehouses` or `user_warehouse` rows) and, where rows have an owner, the `record_view` rule (users without it only see their own records). No dedicated permission is required beyond login, except the real-time counter which needs the `real_time_sales_counter` permission.",
            "x-section": "Dashboard & Reports"
        },
        {
            "name": "Report Questions",
            "description": "\"AI Reports\": a curated list of natural-language business questions (e.g. *Which products are running out?*) backed by pre-built queries. `run` executes one question for a date range/warehouse and returns rows, comparison values and generated insights. Permission `AI_Reports`.",
            "x-section": "Dashboard & Reports"
        },
        {
            "name": "Reports",
            "description": "The reporting suite. All list-style reports follow the standard pagination contract (`limit`, `page`, `SortField`, `SortType`, `search`; `limit=-1` returns everything) and return `totalRows` next to the rows. Date-ranged reports take `from`/`to` (`YYYY-MM-DD`) and default to the last 30 days when omitted unless noted. Every report is scoped to the caller's assigned warehouses and honours `record_view`. Each report has its own permission slug (shown per endpoint): `Reports_sales`, `Reports_purchase`, `Reports_customers`, `Reports_suppliers`, `Reports_profit`, `Warehouse_report`, `stock_report`, `users_report`, `product_report`, `Top_products`, `Top_customers`, and the newer `*_report` slugs.",
            "x-section": "Dashboard & Reports"
        },
        {
            "name": "Serial Number Reports",
            "description": "Reports over serialised units (`product_serials`): available stock, sold units, movement history and per-product counts by status. Permission `serial_numbers_report`. Warehouse-scoped to the caller.",
            "x-section": "Dashboard & Reports"
        },
        {
            "name": "Brands",
            "description": "Manufacturer / brand of a product, with an optional 200×200 logo stored under `/images/brands/`. Permission slug: `brand`.",
            "x-section": "Catalog"
        },
        {
            "name": "Categories",
            "description": "Top-level product classification. A product has one primary `category_id` and may belong to several categories through the multi-category feature. Categories carry a `code`, a `name` and an optional `icon` used by the storefront. Permission slug: `category` (view/add/edit/delete are all checked against the Category policy).",
            "x-section": "Catalog"
        },
        {
            "name": "Product Batches",
            "description": "Lot / batch tracking with expiry dates for products flagged `is_batch_tracked` (pharmacy, food). Each batch belongs to one product (optionally one variant) in one warehouse and carries `batch_no`, `mfg_date`, `expiry_date`, `qty`, `unit_cost` and a `status` (`active`, `quarantined`, `expired`, `written_off`). Sales consume batches FEFO (first-expired-first-out). Batch quantities and `product_warehouse.qte` are kept in sync: editing or writing off a batch adjusts the warehouse stock by the delta. All endpoints return 404 when the batch module is not installed. Permissions: `view_batches`, `manage_batches`, `writeoff_batches`; batches are further limited to the caller's warehouses.",
            "x-section": "Catalog"
        },
        {
            "name": "Products",
            "description": "Everything you sell or stock. A product has a **type**:\n\n| `type` | Meaning |\n|---|---|\n| `is_single` | one SKU with its own cost, price and stock per warehouse |\n| `is_variant` | a parent with several **variants** (size, colour…), each with its own code, cost, price and stock |\n| `is_service` | not stocked; price only (`manage_stock = 0`) |\n| `is_combo` | a bundle assembled from other single products (`materiels`) |\n\nStock is kept per warehouse in `product_warehouse` (`qte`), optionally per variant, with an optional shelf **location**. Prices: `cost`, `price` (retail), `wholesale_price`, `min_price` (floor for POS discounts), optional quantity **price tiers** and multi-**packs**. Tax: `tax_method` `1` = exclusive, `2` = inclusive with `TaxNet` percent. Discount on the product: `discount_method` `1` = percent, `2` = fixed with `discount`.\n\nCreate/update accept `multipart/form-data` because of the image upload, so array-valued fields (`variants`, `materiels`, `warehouses`, `packs`, `price_tiers`, `tags`, `labels`, `faqs`…) are sent as **JSON-encoded strings**, and booleans as `\"true\"`/`\"false\"` or `1`/`0`.\n\nPermissions: `products_view`, `products_add`, `products_edit`, `products_delete`, `product_import`, `barcode_view`, `count_stock`, `opening_stock_import`, `Reports_quantity_alerts`.",
            "x-section": "Catalog"
        },
        {
            "name": "Promotions",
            "description": "Rule-based discounts applied automatically (or via a **code**) in POS and sales. A promotion has a `kind` (`discount` = simple price reduction, `promotion` = campaign), a `discount_type` (`percentage` or `fixed`) and `discount_value`, and optional conditions: date range (`starts_at`/`ends_at`), time-of-day window, minimum cart total or item count, product scope (`all` or `specific` products), warehouses, usage caps (total and per customer), `stackable` with other promotions and a `priority` for ordering. Every application is logged as a *usage* row for reporting. Permission slug: `promotion`.",
            "x-section": "Catalog"
        },
        {
            "name": "Serial Numbers",
            "description": "Unit-level tracking (serial / IMEI) for products flagged `is_imei`. Each serial belongs to a product (optionally variant) and a warehouse, has a `status` (`available`, `sold`, `returned`, `damaged`, `reserved`, …) and a movement log describing every change (purchase, sale, return, transfer, manual). Serials are created when a purchase is received and consumed when a sale is made.",
            "x-section": "Catalog"
        },
        {
            "name": "Size Guides",
            "description": "Size charts (columns × rows, optional image) attached to products and displayed on the storefront product page. Permission slug: `size_guides`.",
            "x-section": "Catalog"
        },
        {
            "name": "Sub-categories",
            "description": "Second level of product classification, always attached to a parent category. Names are unique **within** a category. `status` hides a sub-category from pickers without deleting it. Permission slug: `subcategory`.",
            "x-section": "Catalog"
        },
        {
            "name": "Units",
            "description": "Units of measure. A **base unit** (e.g. *Piece*, *Kg*) has no `base_unit`; a **sub-unit** (e.g. *Box of 12*, *Gram*) points to its base unit and converts with `operator` (`*` or `/`) and `operator_value`. Products store cost and price per base unit and can use a sub-unit for purchasing and another for selling. Permission slug: `unit`.",
            "x-section": "Catalog"
        },
        {
            "name": "Vehicle Fitment",
            "description": "Auto-parts feature: a catalogue of vehicle **makes** and **models**, and per-product **fitment** rows (make, model, year range, engine) saying which vehicles a part fits. POS and the storefront use it to hide incompatible parts once a vehicle is selected. Products without fitment rows are *universal* and always shown. The feature can be switched off in settings (`enabled` flag in responses). Managing makes/models/fitments requires `products_edit`; reading uses `products_view` or plain authentication.",
            "x-section": "Catalog"
        },
        {
            "name": "Stock Adjustments",
            "description": "Manual stock corrections for one warehouse. An adjustment has a header (`date`, `warehouse_id`, `notes`, auto `Ref` like `AD_1112`) and detail lines, each adding (`type: add`) or removing (`type: sub`) a quantity of a product or variant. Stock is changed immediately on create, and reversed/re-applied on update and delete. Combo products adjust their component stock. Batch-tracked products can allocate the quantity to specific batches. Access follows the caller's warehouses and the *record view* rule (users without it see only their own documents). Permissions: `adjustment_view`, `adjustment_add`, `adjustment_edit`, `adjustment_delete`.",
            "x-section": "Inventory"
        },
        {
            "name": "Stock Damages",
            "description": "Record damaged / lost goods. A damage document always **subtracts** the quantity of each line from the warehouse (never below 0), including combo components. Deleting or editing reverses the previous subtraction first. Permissions: `damage_view` (also used for create) plus `adjustment_edit` / `adjustment_delete` for update and delete.",
            "x-section": "Inventory"
        },
        {
            "name": "Stock Transfers",
            "description": "Move stock between two warehouses. A transfer has a header (`from_warehouse`, `to_warehouse`, `date`, `statut`, tax/discount/shipping, notes) and detail lines with quantities in a purchase unit. **New transfers start with `approval_status = pending` and do not move stock** until approved. Once approved, `statut` decides the movement: `completed` = stock leaves the source and arrives at the destination; `sent` = stock leaves the source only; `pending` = nothing moves. Permissions: `transfer_view`, `transfer_add`, `transfer_edit`, `transfer_delete`.",
            "x-section": "Inventory"
        },
        {
            "name": "Warehouse Locations",
            "description": "Optional bin / shelf codes inside a warehouse (e.g. `A-03-2`). A product can be assigned one location per warehouse, shown on picking lists and receipts. Codes are unique within a warehouse and can be deactivated instead of deleted. Permission slug: `warehouse_locations`.",
            "x-section": "Inventory"
        },
        {
            "name": "Warehouses",
            "description": "Physical stock locations (shops, depots). Stock quantities are always kept **per warehouse** in `product_warehouse`, so creating a warehouse also creates a zero-stock row for every existing product and variant. Users are either allowed into all warehouses or into an explicit list, and every stock-related endpoint filters by that scope. Permission slug: `warehouse`.",
            "x-section": "Inventory"
        },
        {
            "name": "Bookings",
            "description": "Appointments / service bookings for a customer: a service product (or free-text product), date and time window, optional delivery details, price, tray/table and salesperson. `status`: `pending`, `confirmed`, `cancelled`, `completed`. Permission policy: Booking view/create/update/delete.",
            "x-section": "Sales"
        },
        {
            "name": "Loyalty Rewards",
            "description": "Loyalty programme catalogue and redemptions. Customers flagged `is_royalty_eligible` earn points on sales (`product.points × quantity`) and can spend them either as a direct discount at checkout or on **rewards**: `gift_card`, `voucher` or `product`, each costing `points_cost` points. A redemption creates a row with a `code` and status `issued` → `fulfilled` (or cancelled, which refunds the points). Manual point adjustments are audited with a note. Permission slug: `loyalty_rewards`; POS endpoints require `Sales_pos`.",
            "x-section": "Sales"
        },
        {
            "name": "Quotations",
            "description": "Price quotes / proformas sent to customers before a sale. A quotation never moves stock. `statut` is `pending` or `sent`; once converted (`GET /api/convert_to_sale_data/{id}` then `POST /api/sales` with `quotation_id`) the quotation records `converted_sale_id`. Batch-tracked lines may carry batch picks that are applied when the sale is created. Permissions: `Quotations_view`, `Quotations_add`, `Quotations_edit`, `Quotations_delete`.",
            "x-section": "Sales"
        },
        {
            "name": "Sale Payments",
            "description": "Money received against a sale. Each payment has a `Ref` (`INV/SL_1111`…), `date`, `payment_method_id`, optional treasury `account_id`, `montant` (amount), `change` and `notes`. Creating, editing or deleting a payment recomputes the sale's `paid_amount` and `payment_statut` and moves the account balance. The list endpoint doubles as the *Payments – Sales* report (requires `Reports_payments_Sales`). Other permissions: `payment_sales_view/add/edit/delete`.",
            "x-section": "Sales"
        },
        {
            "name": "Sale Return Payments",
            "description": "Refunds paid to a customer against a sale return (`Ref` `INV/RT_1111`…). Same fields and rules as sale payments, but money goes **out**: account balances are decreased on create and restored on delete. List requires `Reports_payments_Sale_Returns`; other actions `payment_returns_view/add/edit/delete`.",
            "x-section": "Sales"
        },
        {
            "name": "Sale Returns",
            "description": "Goods a customer brings back. A return usually references the original sale (`sale_id`, so lines can be pre-filled from it) but can also be free-standing. `statut` `received` puts the returned quantity **back into stock** (and re-marks serials as returned / credits batches); `pending` does not. Refunds are recorded through *Sale Return Payments* and drive `payment_statut` (`unpaid`, `partial`, `paid`). A sale that has a return can no longer be edited or deleted. Permissions: `Sale_Returns_view`, `Sale_Returns_add`, `Sale_Returns_edit`, `Sale_Returns_delete`, `payment_returns_view`.",
            "x-section": "Sales"
        },
        {
            "name": "Sales",
            "description": "Customer sales / invoices (back-office and POS). A sale has a header (customer, warehouse, date, `statut`, order-level tax/discount/shipping, notes, optional sales agent and salesperson) and detail lines. **Statuses**: `statut` is `completed` (stock is deducted), `pending` or `ordered` (no stock movement); `payment_statut` is `unpaid`, `partial` or `paid` and is recomputed from payments. `shipping_status` is set through the Shipments endpoints.\n\nAmounts are stored in the base currency; when multi-currency is enabled the document keeps a `currency_id` / `exchange_rate` snapshot and detail endpoints return amounts converted into the document currency with `currency_symbol`. Documents attached to a sale (PDF, images) are managed through the `/documents` endpoints. Each protected endpoint also enforces the warehouse scope and *record view* rule of the caller.\n\nPermissions: `Sales_view`, `Sales_add`, `Sales_edit`, `Sales_delete`, `Sales_pos`, `payment_sales_view`.",
            "x-section": "Sales"
        },
        {
            "name": "Shipments",
            "description": "Delivery tracking for a sale. Each sale has at most one shipment record (`Ref`, `delivered_to`, `shipping_address`, `shipping_details`, `status`); saving it also writes `shipping_status` on the sale. Typical statuses: `ordered`, `packed`, `shipped`, `delivered`, `cancelled`. Permission slug: `shipment`.",
            "x-section": "Sales"
        },
        {
            "name": "Subscriptions",
            "description": "Recurring sales: a customer subscribes to a product for `total_cycles` billing cycles (`weekly`, `monthly`, `yearly`); on each `next_billing_date` a sale/invoice is generated automatically and `remaining_cycles` decreases. `status`: `active`, `canceled`, `completed`. Permission slug: `subscription_product`.",
            "x-section": "Sales"
        },
        {
            "name": "Purchase Payments",
            "description": "Money paid to a supplier against a purchase (`Ref` `INV/PR_1111`…). Fields: `date`, `payment_method_id`, optional treasury `account_id`, `montant`, `change`, `notes`. Creating a payment **decreases** the account balance and recomputes the purchase's `paid_amount` / `payment_statut`; editing and deleting reverse accordingly. The list endpoint is the *Payments – Purchases* report (`Reports_payments_Purchases`); other actions use `payment_purchases_view/add/edit/delete`.",
            "x-section": "Purchases"
        },
        {
            "name": "Purchase Return Payments",
            "description": "Refunds received from a supplier against a purchase return (`Ref` `INV/RT_1111`…). Same fields as purchase payments; money comes **in**, so account balances increase on create and decrease on delete. List requires `Reports_payments_purchase_Return`; other actions `payment_returns_view/add/edit/delete`.",
            "x-section": "Purchases"
        },
        {
            "name": "Purchase Returns",
            "description": "Goods sent back to a supplier, usually referencing the original purchase. `statut` `completed` **removes** the returned quantity from stock (and marks serials returned / debits batches); `pending` does not. Refunds received from the supplier are recorded as *Purchase Return Payments*. Permissions: `Purchase_Returns_view`, `Purchase_Returns_add`, `Purchase_Returns_edit`, `Purchase_Returns_delete`, `payment_returns_view`.",
            "x-section": "Purchases"
        },
        {
            "name": "Purchases",
            "description": "Supplier purchase orders / bills. A purchase has a header (supplier, warehouse, date, `statut`, order-level tax/discount/shipping, notes) and detail lines with cost per purchase unit. **Statuses**: `statut` is `received` (stock is added, batches created, serials registered), `pending` or `ordered` (no stock movement); `payment_statut` is `unpaid`, `partial` or `paid`, recomputed from purchase payments. Multi-currency documents keep a currency snapshot. A purchase that has a return can no longer be edited or deleted. Permissions: `Purchases_view`, `Purchases_add`, `Purchases_edit`, `Purchases_delete`, `payment_purchases_view`.",
            "x-section": "Purchases"
        },
        {
            "name": "Cash Registers",
            "description": "Cash drawer sessions per cashier and warehouse. A cashier **opens** a register with an opening float, records cash **in/out** movements during the shift, and **closes** it by counting the cash; the close computes `expected_cash = opening + cash_in − cash_out + POS sales of the shift` and the `difference`. The report lists sessions for managers (`cash_register_report`).",
            "x-section": "Point of Sale"
        },
        {
            "name": "Customer Display",
            "description": "Second-screen display facing the customer. An admin **generates** a 24-hour token that opens the public `/customer-display?token=…` page; the POS then **broadcasts** the cart (WebSocket event plus a cached copy) and the display **polls** the last cart as a fallback. Several screens are supported through `screen_id`.",
            "x-section": "Point of Sale"
        },
        {
            "name": "Kitchen Orders",
            "description": "Kitchen display system (KDS) for restaurant mode. A POS sale can be sent to the kitchen as a **ticket** (`kitchen_orders`) that moves through `pending` → `preparing` → `completed` (or `on_hold`). Cooks bump individual lines or the whole ticket, tickets can be assigned to a staff member and, once completed, *dispatched* to a warehouse (display-only, no stock movement). Prep **stations** map product categories to screens so each station sees only its items, and a public *Order Ready* screen (token-guarded) shows token numbers being prepared / ready. Permissions: `kitchen_display_view` and `kitchen_display_manage`.",
            "x-section": "Point of Sale"
        },
        {
            "name": "POS",
            "description": "Point-of-sale screen endpoints. The POS loads its lookups and product grid once, keeps the grid fresh with incremental stock deltas, can **hold** a cart as a *draft sale* and resume it later, and finally submits the ticket as a completed sale with one or more payment lines (cash, card, wallet, …). POS sales are regular sales flagged `is_pos = 1`. All endpoints require the `Sales_pos` permission (shown as `Pos_view`) and the warehouse must be assigned to the cashier.",
            "x-section": "Point of Sale"
        },
        {
            "name": "Trays",
            "description": "Trays / tables used by restaurant-style POS and bookings to identify where an order sits. Simple name + description records (Tray policy view/create/update/delete).",
            "x-section": "Point of Sale"
        },
        {
            "name": "Customers",
            "description": "Customers (called *clients* in the database and URLs) are the people or companies you sell to. A customer record holds contact details, tax number, an **opening balance** (debt carried over from before Stocky), a **credit limit** and loyalty **points**. Every sale, quotation, sale return and payment references a customer, and the endpoints here also expose the customer *ledger*: sales, payments, quotations and returns for one customer, and bulk \"pay due\" actions that settle several unpaid documents in one go.\n\nA customer may optionally have an **online-store account** (`ecommerce_clients`) that lets them log in to the storefront and a **client-portal login** (`portal_clients`) for the B2B client portal; both are managed through endpoints in this group.\n\nPermissions: `Customers_view`, `Customers_add`, `Customers_edit`, `Customers_delete`, `customers_import`, `pay_due`, `pay_sale_return_due`.",
            "x-section": "People"
        },
        {
            "name": "Customer Store Accounts",
            "description": "Login accounts that let a customer sign in to the **online storefront** (`ecommerce_clients` table). A store account is always linked to a customer record (`client_id`); it carries its own `email`, `username`, `password`, `status` (active flag) and `is_blocked`. Two families of endpoints exist: `clients_without_ecommerce` lists customers that have **no** account yet and creates/updates accounts by *customer id*, while `ecommerce_clients` lists and manages the accounts themselves by *account id*. All use the Customers permissions (`Customers_view/add/edit/delete`).",
            "x-section": "People"
        },
        {
            "name": "Roles & Permissions",
            "description": "A **role** is a named bundle of permission slugs (for example `Customers_view`, `Sales_add`, `pay_due`). Every user has one role, and each protected endpoint in this documentation lists the slug it checks. Role id `1` (Owner) is protected and cannot be edited through the API.\n\nPermissions for this group: `permissions_view`, `permissions_add`, `permissions_edit`, `permissions_delete`.",
            "x-section": "People"
        },
        {
            "name": "Suppliers",
            "description": "Suppliers (called *providers* in the database and URLs) are the companies you buy from. A supplier holds contact and tax details, an **opening balance** (what you owed them before Stocky) and a **credit limit**. Purchases, purchase returns and their payments reference a supplier. The *supplier details* endpoints expose the supplier ledger, and the *pay due* endpoints settle several unpaid purchases or purchase returns at once.\n\nPermissions: `Suppliers_view`, `Suppliers_add`, `Suppliers_edit`, `Suppliers_delete`, `Suppliers_import`, `pay_supplier_due`, `pay_purchase_return_due`.",
            "x-section": "People"
        },
        {
            "name": "Users",
            "description": "Staff accounts that log in to the admin panel and POS. Each user has exactly one **role** (which carries the permissions), an active flag `statut`, an avatar, and a warehouse scope: either `is_all_warehouses` or an explicit list of assigned warehouses. The `record_view` flag decides whether the user sees **all** documents or only the ones they created themselves. Profile endpoints let the logged-in user edit their own data and password.\n\nPermissions: `users_view`, `users_add`, `users_edit`, `users_delete`.",
            "x-section": "People"
        },
        {
            "name": "Accounting: Chart of Accounts",
            "description": "General-ledger accounts for the double-entry accounting module (`acc_chart_of_accounts`). Each account has a `code`, `name`, `type` (`asset`, `liability`, `equity`, `income`, `expense`), optional `parent_id` / `level` for hierarchy, an optional link to a treasury account (`account_id`) and an `is_active` flag. Permission slug: `chart_of_accounts`. Endpoints return empty data when the accounting tables are not migrated.",
            "x-section": "Finance"
        },
        {
            "name": "Accounting: Dashboard",
            "description": "KPI summary for the accounting module home page (`accounting_dashboard`).",
            "x-section": "Finance"
        },
        {
            "name": "Accounting: Journal Entries",
            "description": "Double-entry journals. An entry has a `date`, `description`, optional `reference_type` / `reference_id` (e.g. `sale`, `purchase`, `manual`) and `lines[]` each hitting a chart-of-accounts account (`coa_id`) with a `debit` or `credit` amount and a `memo`. Entries are created as `draft` (may be unbalanced) and become immutable once **posted**; posting requires debits = credits. Permission slug: `journal_entries`.",
            "x-section": "Finance"
        },
        {
            "name": "Accounting: Reports",
            "description": "Financial statements computed from **posted** journal lines: trial balance, profit & loss, balance sheet, plus a VAT/tax summary computed from sales and purchases. Permissions: `trial_balance`, `accounting_profit_loss`, `balance_sheet`, `accounting_tax_report`.",
            "x-section": "Finance"
        },
        {
            "name": "Accounts",
            "description": "Treasury accounts (cash drawers, bank accounts). Every payment, deposit, expense and money transfer can reference an account and moves its `balance`; the balance therefore reflects the sum of movements since `initial_balance`. Permission slug: `account`.",
            "x-section": "Finance"
        },
        {
            "name": "Currencies",
            "description": "Currency table used by settings and the multi-currency module. The **default** currency (System Settings) always has `exchange_rate = 1`; other rates are *units of this currency per 1 base unit*. Documents snapshot the currency and rate at creation time. Permission slug: `currency`.",
            "x-section": "Finance"
        },
        {
            "name": "Deposit Categories",
            "description": "Labels used to classify deposits (`title`). Permissions follow the deposit slugs.",
            "x-section": "Finance"
        },
        {
            "name": "Deposits",
            "description": "Money coming into an account that is not a sale (capital injection, owner deposit, loan…). Each deposit has a `deposit_ref` (`DEP_1111`…), date, category, account, amount and description; creating one **increases** the account balance, deleting reverses it. Users without record view see only their own deposits. Permissions: `deposit_view`, `deposit_add`, `deposit_edit`, `deposit_delete`.",
            "x-section": "Finance"
        },
        {
            "name": "Expense Categories",
            "description": "Labels used to classify expenses (`name`, `description`). Users without record view see only the categories they created.",
            "x-section": "Finance"
        },
        {
            "name": "Expenses",
            "description": "Money going out of an account for running costs (rent, utilities…). An expense has a `Ref` (`EXP_1111`…), date, warehouse, category, account, payment method, amount and `details` text, and can carry attached documents. Creating one **decreases** the account balance; editing and deleting re-balance. Scoped by warehouse and record view. Permissions: `expense_view`, `expense_add`, `expense_edit`, `expense_delete`.",
            "x-section": "Finance"
        },
        {
            "name": "Money Transfers",
            "description": "Move money between two treasury accounts. Creating a transfer debits the source and credits the destination (the source must have enough balance); editing or deleting re-balances both. Permission slug: `transfer_money`.",
            "x-section": "Finance"
        },
        {
            "name": "Payment Methods",
            "description": "Tender types offered in payments (Cash, Card, Bank transfer…). The three default methods (ids 1–3) cannot be renamed or deleted but may be deactivated; inactive methods disappear from new-payment pickers while history keeps showing them. Permission slug: `payment_methods`.",
            "x-section": "Finance"
        },
        {
            "name": "ZATCA e-Invoicing",
            "description": "Saudi Arabia e-invoicing (Fatoora). **Phase 1** adds the ZATCA QR code to printed receipts and is driven by the `company.*` fields; **Phase 2** clears/reports invoices with the ZATCA gateway: configure the organisation, onboard with an OTP from the Fatoora portal (generates a CSR, obtains compliance and production CSIDs), then submit sales as invoices and sale returns as credit notes, manually or automatically (`auto_submit`). Environments: `sandbox`, `simulation`, `production` — switching environment resets the issued credentials. Permission slug: `zatca_settings`.",
            "x-section": "Finance"
        },
        {
            "name": "Attendances",
            "description": "Daily attendance records. On save, the clock-in/out times are compared with the employee's office shift for that weekday to compute `late_time`, `depart_early`, `overtime` and `total_work` (all `HH:MM`). Days with no shift configured are stored as plain `present` with zero lateness. Users without the `record_view` privilege only see the attendances they recorded themselves. Permission slug: `attendance`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Companies",
            "description": "Legal entities / branches of the HR module. Every department, designation, office shift and employee belongs to a company. Soft-deleted. Permission slug: `company`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Departments",
            "description": "Departments inside a company, optionally with a department head (an employee). Permission slug: `department`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Designations",
            "description": "Job titles, scoped to a company and a department. Permission slug: `designation`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Employee Accounts",
            "description": "Bank accounts attached to an employee (used on payslips). Permissions reuse the employee slugs (`add_employee`, `edit_employee`, `delete_employee`).",
            "x-section": "Human Resources"
        },
        {
            "name": "Employee Experience",
            "description": "Previous work experience entries of an employee. Permissions reuse the employee slugs.",
            "x-section": "Human Resources"
        },
        {
            "name": "Employees",
            "description": "HR employee records: identity, contact, organisation (company / department / designation / shift), employment details (type, joining / leaving dates, salary, hourly rate), leave balance and social profiles. Bank accounts and work experience live in their own tags. Permission slugs: `view_employee`, `add_employee`, `edit_employee`, `delete_employee`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Holidays",
            "description": "Company holidays (title, period, description). Permission slug: `holiday`.",
            "x-section": "Human Resources"
        },
        {
            "name": "HR Lookups",
            "description": "Small unauthenticated-permission helper lists used by HR forms to cascade select boxes (company → departments / shifts / employees, department → designations). They only require a logged-in user.",
            "x-section": "Human Resources"
        },
        {
            "name": "Leaves",
            "description": "Leave requests: a period (`start_date`..`end_date`, inclusive day count in `days`), a leave type, an optional attachment image and a `status` (`pending`, `approved`, `rejected`). Saving an **approved** leave deducts the days from the employee's `remaining_leave`; requests exceeding the balance are refused with `isvalid: false`. Permission slug: `leave` (also used by leave types).",
            "x-section": "Human Resources"
        },
        {
            "name": "Leave Types",
            "description": "Catalogue of leave types (annual, sick, …) referenced by leaves. Permission slug: `leave`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Office Shifts",
            "description": "Weekly working-hours templates per company: an *in* and *out* time for each weekday (stored as `H:iA`, e.g. `09:00AM`; returned without the AM/PM suffix by the list). Used by attendance to compute lateness and overtime. Permission slugs: `office_shift` (create/update/delete/view abilities).",
            "x-section": "Human Resources"
        },
        {
            "name": "Payroll",
            "description": "Salary payments to employees. Each payroll gets a generated `Ref`, is marked `paid`, and when an `account_id` is supplied the treasury account balance is decreased (and restored on update/delete). Permission slug: `payroll`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Recruitment",
            "description": "Applicant tracking: job **categories**, **jobs** (`job_type` full_time|part_time|contract|internship|remote, `status` open|closed|…), **candidates** (with resume / photo uploads), **applications** linking a candidate to a job through the pipeline `applied → screening → shortlisted → interview → offered → hired | rejected`, **interviews** (scheduling one auto-advances the application to `interview`), plus a dashboard and reports. Permission slugs: `recruit_category`, `recruit_job`, `recruit_candidate`, `recruit_application`, `recruit_interview`.",
            "x-section": "Human Resources"
        },
        {
            "name": "Contracts",
            "description": "Contract management. A contract has a `contract_number` (auto-generated when omitted), a `party_type` (`customer` with `client_id`, or `employee` with `employee_id`), optional `project_id`, `subject`, `value`, free-text `type`, dates and a `status` (`draft`, `active`, `expired`, `cancelled`). Sub-resources: attachments, comments, internal notes, renewals, tasks. **Templates** (`/api/contracts-templates`) are HTML documents with merge fields such as `{customer_name}` that can be rendered or exported as PDF for a given contract. Permission slug: `contracts`.",
            "x-section": "Work Management"
        },
        {
            "name": "Document Archive",
            "description": "Company file archive: documents (any file up to 50 MB) organised in nested **folders**, with tags, reference, expiry date, star flag and an append-only **version history**. Permission slugs: `documents_view`, `documents_add`, `documents_edit`, `documents_delete`.",
            "x-section": "Work Management"
        },
        {
            "name": "Knowledge Base",
            "description": "Internal help centre: article **groups** and **articles** (Markdown/HTML `content`, unique `slug` per group, optional `published_at`, `is_internal` flag hiding the article from non-managers) with thumbs-up/down feedback. Managing requires `knowledge_base_view`; reading is open to any authenticated user (internal articles only for managers).",
            "x-section": "Work Management"
        },
        {
            "name": "Meetings",
            "description": "Meeting scheduler: meetings (`type` physical|online, `status` scheduled|ongoing|completed|cancelled) with participants (users), attendance tracking, notes / decisions / action items, file attachments, invitation notifications and an activity log. Permission slugs: `meeting` (CRUD), `meeting_attendance`, `meeting_report`.",
            "x-section": "Work Management"
        },
        {
            "name": "Project Milestones",
            "description": "Deliverables inside a project with a `due_date`, `status` (`pending`, `in_progress`, `completed`, `delayed`), `progress` percentage, optional `budget` and a manual `position` order. Completing a milestone forces progress to 100 and stamps `completed_on`; any other status caps progress at 99 and clears the completion date. Permission slug: `project_milestones`.",
            "x-section": "Work Management"
        },
        {
            "name": "Projects",
            "description": "Projects belong to a company and a client, run between `start_date` and `end_date`, carry a `status` (`not_started`, `progress`, `on_hold`, `completed`, `cancelled`) and are assigned to one or more employees (`assigned_to` ids). Permission slug: `projects`.",
            "x-section": "Work Management"
        },
        {
            "name": "Project Time Logs",
            "description": "Hours logged against a project (optionally a task and an employee). `amount` = hours × hourly rate when `billable`. Permission slug: `project_time_logs`.",
            "x-section": "Work Management"
        },
        {
            "name": "Project Workspace",
            "description": "Aggregated views for the project workspace UI: dashboard KPIs, a one-call `meta` lookup for forms, and three paginated reports (delivery per project, workload per person, milestone slippage). Reports require the `project_reports` permission.",
            "x-section": "Work Management"
        },
        {
            "name": "Tasks",
            "description": "Tasks inside a project: dates, `priority` (`low`, `medium`, `high`), `estimated_hour`, `task_progress` (0–100) and `status` (`not_started`, `progress`, `completed`, `cancelled`), assigned to employees. A kanban board view and two status-change shortcuts are included. Permission slug: `tasks`.",
            "x-section": "Work Management"
        },
        {
            "name": "Service Checklists",
            "description": "Reusable intake checklist **categories** and **items** (e.g. *Screen → Cracked*, *Buttons → Power*). Jobs copy the selected items so later edits to the catalogue do not alter history. Permission slug: `service_jobs`.",
            "x-section": "Service Jobs"
        },
        {
            "name": "Service Job Payments",
            "description": "Payments and refunds recorded against a service job. Each payment gets a `Ref`, may debit/credit a treasury account and recomputes the job's `paid_amount` / `payment_status`. Permission slug: `service_jobs`.",
            "x-section": "Service Jobs"
        },
        {
            "name": "Service Job Photos",
            "description": "Photos attached to a job at a given `stage` (`intake`, `before`, `after`, `delivery`). Permission slug: `service_jobs`.",
            "x-section": "Service Jobs"
        },
        {
            "name": "Service Jobs",
            "description": "Repair / service work orders. A job tracks a customer's device (`service_item`, brand, model, serial, IMEI, condition), the reported issue and diagnosis, a quote (`quote_amount`, `quote_valid_until`), a technician, scheduled dates, an intake **checklist**, billable **items** (parts, labor, other — parts deduct stock on delivery), **payments** and **photos**. Status flow: `pending → intake → diagnostic → quoted → approved → in_progress → ready → delivered` (or `declined`, `cancelled`, `completed`). `payment_status` is derived: `unpaid`, `partial`, `paid`. Permission slug: `service_jobs` (all abilities).",
            "x-section": "Service Jobs"
        },
        {
            "name": "Service Reports",
            "description": "Reports for the service module: job list with KPIs, checklist completion rate, and per-customer maintenance history. Permissions: `service_jobs_report`, `checklist_completion_report`, `customer_maintenance_history_report`.",
            "x-section": "Service Jobs"
        },
        {
            "name": "Service Technicians",
            "description": "Technicians that can be assigned to jobs (name, phone, email, active flag). Permission slug: `service_jobs`.",
            "x-section": "Service Jobs"
        },
        {
            "name": "Asset Assignments",
            "description": "Check-out / check-in history: who holds which asset, since when, due-back date and condition. An asset can only have one open assignment; checking in frees it. Permission slug: `asset_assignments`.",
            "x-section": "Assets"
        },
        {
            "name": "Asset Categories",
            "description": "Categories used to group assets (`assets_category`). Permission slug: `assets`.",
            "x-section": "Assets"
        },
        {
            "name": "Asset Maintenance",
            "description": "Maintenance jobs on assets: `type` (`service`, `repair`, `inspection`, `calibration`, `upgrade`, `other`), `status` (`scheduled`, `in_progress`, `completed`, `cancelled`), cost and dates. An open job puts the asset into `maintenance` status; completing it restores the previous status. Permission slug: `asset_maintenance`.",
            "x-section": "Assets"
        },
        {
            "name": "Assets",
            "description": "Fixed-asset register: each asset has a unique `tag`, name, category, serial number, purchase data (`purchase_date`, `purchase_cost`, `supplier`, `warranty_expiry`), depreciation settings (`depreciation_method` none|straight_line|declining_balance, `useful_life_months`, `salvage_value`), a `status` (`in_use`, `available`, `maintenance`, `retired`, …), a home `warehouse_id`, a current holder (`assigned_to_id`, a user) and verification dates (`last_verification`, `next_validation`). Lists are scoped to the caller's warehouses. Permission slug: `assets`.",
            "x-section": "Assets"
        },
        {
            "name": "Asset Transfers",
            "description": "Moves of an asset between warehouses. Both ends must be warehouses the caller can access. Deleting a transfer undoes the move. Permission slug: `asset_transfers`.",
            "x-section": "Assets"
        },
        {
            "name": "Asset Workspace",
            "description": "Aggregated pages for the asset module: dashboard, shared lookups, asset details, disposal, and the register / maintenance / custody reports. Permission slug: `assets`.",
            "x-section": "Assets"
        },
        {
            "name": "Commission Programs",
            "description": "Named commission schemes with an optional validity window and active flag. Rules belong to a program.",
            "x-section": "Commissions"
        },
        {
            "name": "Commission Receipts",
            "description": "Payout documents: a receipt pays a set of approved commissions of one agent and marks them `paid`.",
            "x-section": "Commissions"
        },
        {
            "name": "Commission Reports",
            "description": "Commission ledger with filters, a status summary and totals per agent.",
            "x-section": "Commissions"
        },
        {
            "name": "Commission Rules",
            "description": "How much to pay: `type` `percentage` or `fixed`, computed on `source` `sale_total` or `paid_amount`, optional `min_threshold` (sale must reach it) and `max_cap`, applied to `all_agents` or a `specific_agent`, ordered by `priority`.",
            "x-section": "Commissions"
        },
        {
            "name": "Commissions",
            "description": "Sales commission engine. A **program** groups **rules**; when a sale is saved (or on demand) the matching rules create `sale_commissions` rows for the sale's **sales agent** with status `pending`. Commissions are then **approved**, grouped into a **receipt** when paid out (status `paid`), or **cancelled**. All responses use the `{success, message, data}` envelope. Permission slugs: `commissions_view`, `commissions_add`, `commissions_edit`, `commissions_delete`.",
            "x-section": "Commissions"
        },
        {
            "name": "Sales Agents",
            "description": "People who earn commissions. Optionally linked to a user account. Referenced by sales (`sales_agent_id`).",
            "x-section": "Commissions"
        },
        {
            "name": "Contact Messages",
            "description": "Messages sent through the storefront contact form. The public submit endpoint is unauthenticated; the admin endpoints need `Messages_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Customer Wallets",
            "description": "Store credit wallets of e-commerce customers: balance, status (`active` / `frozen`), transaction ledger and manual adjustments. Permission slug: `ewallet`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Flash Sales",
            "description": "Time-boxed product promotions shown on the storefront: a named sale with `starts_at` / `ends_at` and a list of products each with its own `percent` or `fixed` discount. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Gift Cards",
            "description": "Prepaid codes redeemable at checkout: `type` `gift_card`, `voucher` or `store_credit`; `status` `active`, `redeemed`, `disabled`, `expired`. Can be generated in batches. Permission slug: `ewallet`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Invite Codes",
            "description": "Registration invite codes (used when `require_invite_code` is on): optional `max_uses`, `expires_at`, active flag, `times_used`. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Newsletter Subscribers",
            "description": "Emails collected by the storefront newsletter form. Permission slug: `Subscribers_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Online Order Returns",
            "description": "Cancellation and return requests submitted by shoppers (`type` `cancellation` | `return`; `status` `requested`, `approved`, `rejected`, `refunded`). Approving triggers the refund (wallet or original method per store settings). Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Online Orders",
            "description": "Orders placed on the storefront. Lifecycle: `pending → confirmed → shipped → delivered`, or `pending → cancelled`. **Confirming** an order books a regular Sale in the chosen warehouse (stock is deducted then), so confirmed orders can no longer be cancelled through this API. `payment_status` is tracked separately (`unpaid`, `pending_proof`, `paid`, …) and manual-payment proofs (GCash / bank transfer) are reviewed here. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Pending Customers",
            "description": "Storefront registrations waiting for admin approval (when `require_admin_approval` is on). Approving activates the account and emails the customer; rejecting deletes it. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Pickup Branches",
            "description": "Which store-enabled warehouses offer *pick up in store* at checkout, with address, hours and contact. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Product Questions",
            "description": "Q&A submitted on product pages: `status` `pending`, `published`, `rejected`. Answering publishes the question by default. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Product Reviews",
            "description": "Customer reviews with a 1–5 `rating`: `status` `pending`, `approved`, `rejected` (auto-approval configurable in store settings). Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Quote Requests",
            "description": "*Request a quote* submissions from product pages (`status` `new`, `handled`, `closed`). The public submit endpoint is rate-limited. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Shipping Methods",
            "description": "Legacy flat-price shipping methods restricted to a list of countries. Prefer Shipping Zones for new setups. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Shipping Zones",
            "description": "Zone-based shipping: a zone is a set of `locations` (country + optional state) with one or more **rates** (`rate_type` `flat`, `price` or `weight`, with `min_value` / `max_value` bands). Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Store Banners",
            "description": "Hero / promotional banners (image, title, position, link, active). Permission slug: `Banners_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Store Collections",
            "description": "Curated product lists shown on the storefront home (`homepage_lineup`) and at `/collections/{slug}`. Products are attached manually with `sort_order` and `pinned`. Permission slug: `Collections_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Store Coupons",
            "description": "Checkout discount codes: `type` `percentage` | `fixed`, `value`, optional `min_order_amount`, `max_discount`, `usage_limit`, `per_customer_limit`, validity window and `enabled` flag. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Store Pages",
            "description": "Static CMS pages (About, Terms, …) with per-locale translations and SEO fields. Only requires a logged-in admin user.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Store Popups",
            "description": "Marketing popups shown on the storefront: `type` `announcement` | `subscription` | `sale`, `trigger` `immediate` | `delay` | `exit`, `frequency` `once` | `session` | `always`, with optional image, CTA and schedule. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Store Settings",
            "description": "Global storefront configuration (`store_settings` row): branding, theme, languages, warehouses feeding the store, registration rules, payment providers, wallet, SEO, custom CSS/JS, and the navigation menus. Booleans are sent as `0`/`1`. Permission slug: `Store_settings_view`. The two `/api/settings/calendar` endpoints (Google Calendar credentials) live in the same controller and need `setting_system`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Tax Rates",
            "description": "Destination-based tax rates per country / state applied at checkout. Permission slug: `Store_settings_view`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Wallet Withdrawals",
            "description": "Payout requests made by customers from their wallet: `pending → approved → paid`, or `rejected`. Approving debits the wallet. Permission slug: `ewallet`.",
            "x-section": "Online Store (Admin)"
        },
        {
            "name": "Checkout & Payments",
            "description": "Cart quoting and order placement for the storefront, plus the browser return URLs of the redirect gateways (PayPal, Paystack, Flutterwave, Razorpay, bKash, SSLCommerz). Payment methods: `credit_card` (Stripe), `paypal`, `paystack`, `flutterwave`, `razorpay`, `bkash`, `sslcommerz`, `wallet`, `cod`, `mobile_money`, `gcash`, `bank_transfer` (the last two need a payment proof), `cash_on_pickup` (requires `pickup_branch_id`). Totals are always recomputed server-side.",
            "x-section": "Storefront"
        },
        {
            "name": "Customer Account",
            "description": "Profile, address and preferences of the signed-in shopper (session guard `store`). Address fields are stored on the linked `Client` record.",
            "x-section": "Storefront"
        },
        {
            "name": "Customer Authentication",
            "description": "Shopper accounts for the online store (`ecommerce_clients`, guard `store`). Cookie/session based: the browser posts a form and receives a redirect; when called via `fetch` with `Accept: application/json` validation errors come back as `422` JSON. Registration can require an invite code, email verification and/or admin approval depending on store settings. Passwords must be at least 8 characters with mixed case, numbers and symbols.",
            "x-section": "Storefront"
        },
        {
            "name": "My Garage",
            "description": "Vehicle fitment (auto-parts stores): choose the vehicle you shop for (kept in session) and save vehicles to your garage when logged in. Returns `404` when the fitment feature is disabled.",
            "x-section": "Storefront"
        },
        {
            "name": "My Loyalty Points",
            "description": "Loyalty programme from the shopper's side: points balance, redeemable rewards and redemption history.",
            "x-section": "Storefront"
        },
        {
            "name": "My Orders",
            "description": "The shopper's own online orders, plus manual-payment proof upload (GCash / bank transfer). All routes require a store session and an account linked to a client.",
            "x-section": "Storefront"
        },
        {
            "name": "My Returns",
            "description": "Cancellation and return requests from the shopper's side. Cancelling a `pending` order is immediate (refunded to wallet/original method); other cases create a `requested` return for admin review.",
            "x-section": "Storefront"
        },
        {
            "name": "My Wallet",
            "description": "The shopper's store-credit wallet: balance and activity, gift-card redemption and withdrawal requests. Returns `403` when the wallet feature is disabled.",
            "x-section": "Storefront"
        },
        {
            "name": "Newsletter",
            "description": "Public newsletter sign-up.",
            "x-section": "Storefront"
        },
        {
            "name": "Payment Gateway Webhooks",
            "description": "Server-to-server notifications from payment providers. Each is verified with the provider's signature scheme before an order is marked paid; the browser return URL and the webhook are idempotent with each other. Return `200` to acknowledge.",
            "x-section": "Storefront"
        },
        {
            "name": "Property Listings",
            "description": "Real-estate storefront: public inquiry form for a listed property.",
            "x-section": "Storefront"
        },
        {
            "name": "Reviews & Questions",
            "description": "Public product reviews / Q&A reading, plus review submission (only for delivered/confirmed purchases) and question asking by signed-in shoppers.",
            "x-section": "Storefront"
        },
        {
            "name": "Storefront Pages & Search",
            "description": "Public storefront helpers: shop listing (HTML), collection redirect, search autocomplete, wholesale price tiers, language and currency switches.",
            "x-section": "Storefront"
        },
        {
            "name": "Wishlist",
            "description": "Per-customer wishlist. Guests receive an empty list; mutations require a store session (`401` otherwise).",
            "x-section": "Storefront"
        },
        {
            "name": "Portal Appointments",
            "description": "Service appointments: the client's service jobs, and booking a new one (created as a `pending` service job with an `APPT_YYYY_#####` reference).",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Authentication",
            "description": "Client portal login (guard `portal`, session cookie shared with the main app). Portal accounts (`portal_clients`) are created by an admin from the customer page and activated through an invitation link valid 48 hours. All portal routes are throttled at 60 requests/minute and return `403` when the account is disabled.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Contracts",
            "description": "Contracts visible to the client (those not flagged *hide from customer*) with attachment download.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Dashboard",
            "description": "Summary figures for the signed-in client.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Invoices",
            "description": "The client's completed sales (invoices) with line details and PDF download.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Knowledge Base",
            "description": "Public (non-internal) knowledge-base articles for portal clients.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Language",
            "description": "Locale switcher and translation bundle for the portal SPA. No authentication required.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Payments",
            "description": "Payments the client has made against invoices.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Profile",
            "description": "Profile, password change and account closure.",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Quotations",
            "description": "The client's quotations, and a form to request a new one (created as `pending` for staff to price).",
            "x-section": "Client Portal"
        },
        {
            "name": "Portal Statement",
            "description": "Account statement / ledger: opening balance, invoices and payments in chronological order with running balance.",
            "x-section": "Client Portal"
        },
        {
            "name": "Mobile Authentication",
            "description": "Login for the Stocky mobile app. Issues a Passport personal access token (`Bearer`) that is then used on the regular `/api/*` endpoints. `ping` is the unauthenticated server handshake.",
            "x-section": "Mobile App"
        },
        {
            "name": "Mobile Device Tokens",
            "description": "Firebase Cloud Messaging device registration for push notifications.",
            "x-section": "Mobile App"
        },
        {
            "name": "Marketing Campaigns",
            "description": "Bulk messaging to customers over **SMS**, **email** or **WhatsApp**. Build **segments** (filters over the customer base, or *all customers*), reusable **templates**, then **campaigns** (`type` sms|email|whatsapp; `status` `draft → scheduled → sending → sent`, or `failed` / `cancelled`). Sending is queued (`SendMarketingCampaign` job) and per-recipient results are tracked. Providers are configured in the marketing **settings** (generic HTTP gateway for SMS / WhatsApp, mail for email). Permission slugs: `marketing_dashboard`, `marketing_campaigns`, `marketing_segments`, `marketing_templates`, `marketing_settings`, `marketing_reports`.",
            "x-section": "Marketing"
        },
        {
            "name": "Google Sheets",
            "description": "Export sales, products and customers to a Google Spreadsheet via OAuth. Permission slug: `google_sheets_settings`. OAuth connect / callback are browser routes (`/google-sheets/connect`).",
            "x-section": "Integrations"
        },
        {
            "name": "Incoming Webhooks",
            "description": "Generic inbound endpoint for third-party systems: `POST /api/webhooks/incoming/{source}`. The payload is logged, signature-checked (per-source secret) and dispatched to the matching handler.",
            "x-section": "Integrations"
        },
        {
            "name": "Jumia",
            "description": "Jumia Seller Center: push price/stock and pull orders. Permission slug: `jumia_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "Mailchimp",
            "description": "Push customers to a Mailchimp audience. Permission slug: `mailchimp_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "Outgoing Webhooks",
            "description": "Push Stocky events (`sale.created`, `product.updated`, … see *Available events*) to external URLs. Each webhook has a secret used to sign deliveries (`X-Stocky-Signature` HMAC-SHA256 of the JSON body); deliveries are retried and logged. Permission slugs: `webhooks_view`, `webhooks_add`, `webhooks_edit`, `webhooks_delete`.",
            "x-section": "Integrations"
        },
        {
            "name": "PrestaShop",
            "description": "PrestaShop webservice: push/pull products, push inventory, pull orders. Permission slug: `prestashop_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "QuickBooks",
            "description": "QuickBooks Online: credentials are written to `.env`, OAuth via `/quickbooks/connect`; customers can be pushed as QuickBooks customers. Any authenticated user (no dedicated permission).",
            "x-section": "Integrations"
        },
        {
            "name": "Salla",
            "description": "Salla (OAuth): push/pull products, push inventory, pull orders, receive webhooks. Permission slug: `salla_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "Shopify",
            "description": "Multi-store Shopify connector. Each **store** (Admin API access token) maps to a warehouse and location; **sync runs** move `products`, `inventory`, `customers`, `orders` (pull only), `collections`, `fulfillments` in either direction; **mappings** link ERP records to Shopify ids; webhooks are received and can be replayed. Permission slugs: `shopify_stores` (manage) and `shopify_sync` (run syncs).",
            "x-section": "Integrations"
        },
        {
            "name": "Slack",
            "description": "Send selected events to a Slack incoming webhook. Permission slug: `slack_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "Stripe",
            "description": "Legacy saved-card endpoints kept for backward compatibility; they no longer touch Stripe.",
            "x-section": "Integrations"
        },
        {
            "name": "Sync Jobs",
            "description": "Background sync jobs shared by the marketplace connectors (currently WooCommerce product sync): poll status, detect stuck workers, cancel.",
            "x-section": "Integrations"
        },
        {
            "name": "Telegram",
            "description": "Send selected events to a Telegram chat through a bot. Permission slug: `telegram_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "WooCommerce",
            "description": "Single-store WooCommerce connector (REST consumer key/secret). Push or pull products, categories, brands, customers; push stock; pull orders into sales. Long syncs run as queued jobs with a progress `token` polled by the progress endpoints (batches are also drained inline while polling when no queue worker runs). Permission slug: `woocommerce_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "Xero",
            "description": "Push contacts and invoices to Xero via OAuth 2. Permission slug: `xero_settings`.",
            "x-section": "Integrations"
        },
        {
            "name": "Fleet: Assignments",
            "description": "Trips: a vehicle handed to a driver from `start_date` (with `start_odometer`) until it is closed with `end_date` / `end_odometer`. A vehicle can have only one `active` assignment. Permission slug: `fleet_assignments`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Fleet: Fuel Logs",
            "description": "Refuelling entries (quantity, unit price, total, odometer, station). Saving a log advances the vehicle odometer. Permission slug: `fleet_fuel`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Fleet: Maintenance",
            "description": "Service and repair records (`type` service|repair|tyres|inspection|insurance|other, `status` scheduled|in_progress|completed) with cost, odometer and next-service reminders. Permission slug: `fleet_maintenance`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Fleet: Reports",
            "description": "Running-cost, fuel, maintenance and driver reports. Permission slug: `fleet_reports`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Fleet: Vehicles",
            "description": "Fleet register: vehicles (`type` car|van|truck|bus|motorcycle|forklift|trailer|other, `fuel_type` petrol|diesel|electric|hybrid|lpg|cng, `status` active|maintenance|inactive|sold) stationed at a warehouse with an assigned driver (employee), odometer, purchase and insurance / registration / inspection expiry dates. Lists are scoped to the caller's warehouses. Permission slugs: `fleet_vehicles_view`, `fleet_vehicles_add`, `fleet_vehicles_edit`, `fleet_vehicles_delete`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Admissions",
            "description": "Inpatient stays: admit a patient to a bed (one open admission per patient), transfer between beds, discharge (computes nights and bed charge). Permission slug: `hms_admissions`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Appointments",
            "description": "Bookings with a doctor (`type` consultation|follow_up|procedure|emergency|teleconsult; `status` scheduled|confirmed|arrived|completed|cancelled|no_show). Double-booking a doctor is refused. Permission slug: `hms_appointments`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Billing",
            "description": "Patient invoices (`status` draft|unpaid|partial|paid|cancelled) with line items (consultation, medicine, lab, bed, other) and payments; overpayment is refused. Permission slug: `hms_billing`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Dashboard",
            "description": "Census / KPI dashboard, form lookups and type-ahead searches. Permission slugs: `hms_dashboard`, `hms_patients_view`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Departments",
            "description": "Clinical departments. Deleting one detaches its doctors and wards. Permission slug: `hms_departments`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Doctors",
            "description": "Practitioners with specialty, department, consultation fee and weekly `availability` (JSON map of weekday → hours). Permission slug: `hms_doctors`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Laboratory",
            "description": "Lab test catalogue and lab orders (`priority` routine|urgent|stat; `status` ordered|sample_collected|in_progress|completed|cancelled) with per-test results and flags. Permission slug: `hms_lab`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Patients",
            "description": "Patient master records with a generated `mrn` (medical record number), demographics, blood group, allergies, emergency contact and insurance. Permission slugs: `hms_patients_view`, `hms_patients_add`, `hms_patients_edit`, `hms_patients_delete`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Reports",
            "description": "Doctor workload, revenue by department, ward occupancy, patient activity and collections by method. Permission slug: `hms_reports`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Visits & Prescriptions",
            "description": "Consultations (`type` opd|emergency|follow_up|teleconsult) recording vitals, complaint, examination, diagnosis, treatment plan and one prescription (lines of medicines, optionally linked to pharmacy products). Completing a visit closes its appointment. Permission slug: `hms_visits`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Hospital: Wards & Beds",
            "description": "Wards (`type` general|private|semi_private|icu|nicu|maternity|isolation) and their beds (`status` available|occupied|maintenance|reserved). `occupied` is controlled by admissions only. Permission slug: `hms_wards`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "MRP: Bills of Materials",
            "description": "Manufacturing recipes. A **BOM** produces `output_qty` of a product from component **lines** (`product_id`, `qty`, `scrap_pct`, `is_optional`) through routed **operations** (work centre, setup and run minutes). BOMs are versioned (`code-V2`, …) and have `status` draft|active|archived. **Work centres** carry hourly cost, overhead rate and efficiency. Permission slug: `mrp_boms`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "MRP: Planning",
            "description": "Material requirements planning: a **planning run** explodes demand (sales, safety stock) against stock over a horizon and produces **suggestions** (`action` make|buy, per level). *Make* suggestions can be accepted into draft production orders. Also the manufacturing dashboard and reports. Permission slugs: `mrp_planning`, `mrp_production` (accept), `mrp_quality` (quality report).",
            "x-section": "Industry Modules"
        },
        {
            "name": "MRP: Production",
            "description": "Production orders (`status` draft → planned → released → in_progress → completed | cancelled; `priority` low|normal|high|urgent). *Release* reserves / issues materials (fails on shortage unless allowed), **work orders** track each routed operation on the shop floor, **quality checks** (in_process | final) record inspected / rejected quantities, and *Complete* books finished goods with actual cost and variance. Permission slugs: `mrp_production`, `mrp_quality`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Real Estate",
            "description": "Property listings for the real-estate storefront theme: **categories**, **properties** (`purpose` sale|rent, `status` available|sold|rented, featured flag, gallery, agent contact, SEO) and public **inquiries** (`status` new|read|responded|closed). Permission slugs: `realestate_properties`, `realestate_categories`, `realestate_inquiries`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Academics",
            "description": "Academic structure: **academic years** (one `is_current`, lockable), **classes** (with `level`), **sections** inside a class (capacity, room, form teacher) and **subjects** (`type` core|elective|optional, credit, pass mark). Permission slug: `school_academics`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Attendance",
            "description": "Daily (or per-subject) class registers: `present`, `absent`, `late`, `excused`, `half_day`. Permission slug: `school_attendance`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Dashboard",
            "description": "KPI dashboard, form lookups and student search. Permission slugs: `school_dashboard`, `school_students_view`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Exams",
            "description": "Exams per academic year and `term` (term_1|term_2|term_3|final|other; `status` draft|scheduled|ongoing|completed|published), their **papers** (one subject × class with max / pass marks and schedule), mark sheets and report cards. Grades are derived from marks. Permission slug: `school_exams`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Fees",
            "description": "Fee **structures** (per year / class, `frequency` once|monthly|termly|yearly), student fee **invoices** (`status` draft|unpaid|partial|paid|cancelled) with items and **payments**; bulk invoice generation per class. Permission slug: `school_fees`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Reports",
            "description": "Enrolment, attendance, absentees, exam performance, fee collection, defaulters and teacher workload. Permission slug: `school_reports`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Students",
            "description": "Student records (generated `admission_number`, demographics, guardian, medical notes) and their **enrolments** per academic year (class, section, roll number; `status` active|promoted|transferred|left|repeated), including year-end promotion. Permission slugs: `school_students_view/add/edit/delete`, `school_enrollment`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Teachers",
            "description": "Teaching staff (optionally linked to HR employees) with their weekly timetable. Permission slug: `school_teachers`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "School: Timetable",
            "description": "Weekly timetable slots per class / section (`day_of_week` mon..sun, start / end time, subject, teacher, room) with clash detection. Permission slug: `school_timetable`.",
            "x-section": "Industry Modules"
        },
        {
            "name": "Backups",
            "description": "Database backups stored under `storage/app/public/backup` and optionally uploaded to S3, Google Drive or Dropbox according to the backup settings. Permission `backup` or `setting_system`.",
            "x-section": "System & Settings"
        },
        {
            "name": "Custom Fields",
            "description": "Definitions and values of admin-defined extra fields on customers (`client`) and suppliers (`provider`). Managing definitions requires `setting_system` for delete only; the other endpoints are available to any authenticated user because customer/supplier forms read and write them.",
            "x-section": "System & Settings"
        },
        {
            "name": "Demo Data",
            "description": "Generate or wipe tagged demo records (products, customers, suppliers, sales, purchases, quotations, expenses) for evaluation installs. Permission `setting_system`. Generated rows are tracked in `demo_records` so reset removes only demo data.",
            "x-section": "System & Settings"
        },
        {
            "name": "Error Logs",
            "description": "Application error log captured in the `error_logs` table with search, context filter, date range and chart series. Permission `report_error_logs`.",
            "x-section": "System & Settings"
        },
        {
            "name": "Languages & Translations",
            "description": "Manage UI languages and their translation catalogues (permission `translations_settings`). Translations are stored in the `translations` table keyed by locale + key; the English catalogue is the master list of keys. `GET /api/translations/{locale}` is public and used by the frontends to load a catalogue; `POST /api/sync-locale` sets the locale cookie for server-rendered pages.",
            "x-section": "System & Settings"
        },
        {
            "name": "Mail Settings",
            "description": "SMTP configuration stored in the `servers` table and a test-send endpoint. Permission `mail_settings` or `setting_system`.",
            "x-section": "System & Settings"
        },
        {
            "name": "Module Settings",
            "description": "Install, enable and disable optional Laravel modules (nwidart/laravel-modules) shipped as ZIP packages. Any authenticated admin-guard user may call these (no additional permission is checked).",
            "x-section": "System & Settings"
        },
        {
            "name": "Notification Templates",
            "description": "Per-locale subject/body templates for the email and SMS notifications Stocky sends (sale, quotation, payment received/sent, purchase, booking, subscription reminder, asset validation due). Permission `notification_template`. Placeholders such as `{contact_name}`, `{number}`, `{total_amount}`, `{paid_amount}`, `{due_amount}`, `{business_name}` are substituted at send time.",
            "x-section": "System & Settings"
        },
        {
            "name": "Payment Gateway Settings",
            "description": "Stripe keys used by the online store checkout. Written to `.env`; the secret is never read back. Permission `payment_gateway` or `setting_system` (`get_payment_gateway_ws` needs `setting_system`).",
            "x-section": "System & Settings"
        },
        {
            "name": "PDF Templates",
            "description": "Look-and-feel of the A4 PDF documents (`sale`, `quotation`, `purchase`): colours, fonts, margins, logo size, table style and which blocks to show. Permission `setting_system`.",
            "x-section": "System & Settings"
        },
        {
            "name": "Security Settings",
            "description": "Active login sessions across all users, remote logout and the personal login-activity report. Permissions: `login_device_management` (or `setting_system`) for sessions; `report_device_management` for the activity report. Session keys are Passport access-token IDs, or `cookie:<hash>` for cookie-authenticated sessions.",
            "x-section": "System & Settings"
        },
        {
            "name": "SMS Settings",
            "description": "Configure the SMS gateways used for notifications (permission `sms_settings` or `setting_system`). Credentials are written to the `.env` file and the config cache is rebuilt. Secrets are never returned by the read endpoint (masked as empty strings).",
            "x-section": "System & Settings"
        },
        {
            "name": "System Health",
            "description": "Server diagnostics (PHP/Laravel versions, extensions, disk, queue, cache, scheduled tasks) as JSON or PDF. Permission `system_health_view`.",
            "x-section": "System & Settings"
        },
        {
            "name": "System Settings",
            "description": "Global configuration of the Stocky instance: company identity, defaults (currency, warehouse, customer, language, timezone), document prefixes, feature toggles, module flags, dashboard layout, appearance/branding, PWA and mobile-app identity, POS behaviour and receipt layout, label-printer hardware and QZ Tray signing. Most endpoints operate on the single `settings` row (there is exactly one). Reads that power the UI shell (`get_Settings_data`, `module_flags`, `sidebar_menu_order`, `settings/dark-mode`, `get_pos_Settings`) need only a valid login; the `_api` variants and every write require `setting_system`, or the narrower area slug shown on each endpoint (`appearance_settings`, `pos_settings`, `business_modules`, `barcode_view`).",
            "x-section": "System & Settings"
        },
        {
            "name": "System Update",
            "description": "Two update mechanisms. **One-click update** (`POST /api/one_click_update`, permission `setting_system`) downloads the latest release from the vendor update server, backs up code and database, deploys and migrates, and rolls back on failure; poll `GET /api/update/progress` while it runs and use `GET /api/update/preflight` first to check tools, permissions, network and disk. **Package update** (`/api/system-update/*`, permission `update_settings`) is a resumable, step-driven flow for uploading a release ZIP manually: upload in chunks → validate → start → call `step` repeatedly until `status` reports completion (each step is short so it survives PHP time limits), with rollback, discard, backup restore and retention management. Every `/api/system-update/*` write returns the full status object.",
            "x-section": "System & Settings"
        }
    ],
    "paths": {
        "/api/Get_employees_by_company": {
            "get": {
                "operationId": "get_api_Get_employees_by_company",
                "tags": [
                    "Employees"
                ],
                "summary": "Employees of a company",
                "description": "`{id, username}` list. Note the capital `G` in the path.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@Get_employees_by_company",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L381-L386",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Company id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/Get_user_profile": {
            "get": {
                "operationId": "get_api_Get_user_profile",
                "tags": [
                    "Users"
                ],
                "summary": "Get my profile",
                "description": "Returns the authenticated user's own record (`users` row without the password).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@GetInfoProfile",
                "x-source": "app/Http/Controllers/UserController.php#L523-L528",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`user` object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "user": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "user": {
                                        "id": 1,
                                        "firstname": "William",
                                        "lastname": "Castillo",
                                        "username": "William Castillo",
                                        "email": "admin@example.com",
                                        "phone": "0123456789",
                                        "avatar": "no_avatar.png"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/coa": {
            "get": {
                "operationId": "get_api_accounting_v2_coa",
                "tags": [
                    "Accounting: Chart of Accounts"
                ],
                "summary": "List chart-of-accounts entries",
                "description": "Paginated accounts (default sort `code asc`). `search` matches code or name.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ChartOfAccountsController@index",
                "x-source": "app/Http/Controllers/AccountingV2/ChartOfAccountsController.php#L16-L54",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "chart_of_accounts",
                        "slug": "chart_of_accounts",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ChartOfAccount"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "`1` active only, `0` inactive only."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`asset`, `liability`, `equity`, `income` or `expense`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_accounting_v2_coa",
                "tags": [
                    "Accounting: Chart of Accounts"
                ],
                "summary": "Create a chart-of-accounts entry",
                "description": "Creates a GL account. Returns HTTP **201** with the row.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ChartOfAccountsController@store",
                "x-source": "app/Http/Controllers/AccountingV2/ChartOfAccountsController.php#L56-L76",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "chart_of_accounts",
                        "slug": "chart_of_accounts",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "ChartOfAccount"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Linked treasury account id."
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-laravel-rules": [
                                            "required",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Account code, max 64."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag (default true)."
                                    },
                                    "level": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Depth in the hierarchy (default 0).",
                                        "type": "integer"
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Account name, max 192."
                                    },
                                    "parent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Parent GL account id."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "asset",
                                            "liability",
                                            "equity",
                                            "income",
                                            "expense"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:asset,liability,equity,income,expense"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`asset`, `liability`, `equity`, `income`, `expense`."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name",
                                    "type"
                                ]
                            },
                            "example": {
                                "code": "1010",
                                "name": "Cash on hand",
                                "type": "asset",
                                "parent_id": null,
                                "level": 1,
                                "account_id": 1,
                                "is_active": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The created account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/coa/{id}": {
            "delete": {
                "operationId": "delete_api_accounting_v2_coa_id",
                "tags": [
                    "Accounting: Chart of Accounts"
                ],
                "summary": "Delete a chart-of-accounts entry",
                "description": "Deletes the GL account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ChartOfAccountsController@destroy",
                "x-source": "app/Http/Controllers/AccountingV2/ChartOfAccountsController.php#L93-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "chart_of_accounts",
                        "slug": "chart_of_accounts",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "ChartOfAccount"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "GL account id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_accounting_v2_coa_id",
                "tags": [
                    "Accounting: Chart of Accounts"
                ],
                "summary": "Update a chart-of-accounts entry",
                "description": "Partially updates code, name, type, parent, level, linked account and active flag.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ChartOfAccountsController@update",
                "x-source": "app/Http/Controllers/AccountingV2/ChartOfAccountsController.php#L78-L91",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "chart_of_accounts",
                        "slug": "chart_of_accounts",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "ChartOfAccount"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "GL account id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account id."
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "level": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Level.",
                                        "type": "integer"
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "parent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Parent id."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "asset",
                                            "liability",
                                            "equity",
                                            "income",
                                            "expense"
                                        ],
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "in:asset,liability,equity,income,expense"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "The updated account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/dashboard": {
            "get": {
                "operationId": "get_api_accounting_v2_dashboard",
                "tags": [
                    "Accounting: Dashboard"
                ],
                "summary": "Accounting dashboard KPIs",
                "description": "`kpi` (`accounts` count, `journals_30d`, `income_30d`, `expense_30d`) and a 30-day `chart` (`labels[]`, `income[]`, `expense[]`) from posted journal lines. Returns zeros when the accounting tables are missing.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\DashboardController@summary",
                "x-source": "app/Http/Controllers/AccountingV2/DashboardController.php#L15-L97",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "accounting_dashboard",
                        "slug": "accounting_dashboard",
                        "policy": "AccountPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`kpi` and `chart`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "kpi": {
                                            "type": "object",
                                            "properties": {
                                                "accounts": {
                                                    "type": "integer",
                                                    "example": 0
                                                },
                                                "journals_30d": {
                                                    "type": "integer",
                                                    "example": 0
                                                },
                                                "income_30d": {
                                                    "type": "number",
                                                    "example": 0
                                                },
                                                "expense_30d": {
                                                    "type": "number",
                                                    "example": 0
                                                }
                                            }
                                        },
                                        "chart": {
                                            "type": "object",
                                            "properties": {
                                                "labels": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "income": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "expense": {
                                                    "type": "array",
                                                    "items": {}
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/journal-entries": {
            "get": {
                "operationId": "get_api_accounting_v2_journal_entries",
                "tags": [
                    "Accounting: Journal Entries"
                ],
                "summary": "List journal entries",
                "description": "Laravel-paginated entries (default 20) with their `lines`, newest first.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\JournalEntriesController@index",
                "x-source": "app/Http/Controllers/AccountingV2/JournalEntriesController.php#L19-L42",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "journal_entries",
                        "slug": "journal_entries",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "JournalEntry"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date from."
                    },
                    {
                        "name": "reference_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Source type (e.g. `manual`, `sale`, `purchase`)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`draft` or `posted`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator with `data[]` and `total`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total": {
                                            "type": "integer",
                                            "example": 0
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_accounting_v2_journal_entries",
                "tags": [
                    "Accounting: Journal Entries"
                ],
                "summary": "Create a journal entry (draft)",
                "description": "Creates a **draft** entry with its lines. Drafts may be unbalanced; balance is enforced when posting. Returns HTTP **201**.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\JournalEntriesController@store",
                "x-source": "app/Http/Controllers/AccountingV2/JournalEntriesController.php#L52-L91",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "journal_entries",
                        "slug": "journal_entries",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "JournalEntry",
                    "JournalEntryLine"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Entry date."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "lines": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "credit": {
                                                    "type": "number",
                                                    "x-laravel-rules": [
                                                        "numeric"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Credit amount."
                                                },
                                                "debit": {
                                                    "type": "number",
                                                    "x-laravel-rules": [
                                                        "numeric"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Debit amount."
                                                }
                                            }
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "At least one line."
                                    },
                                    "reference_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Source document id."
                                    },
                                    "reference_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Source type (default `manual`)."
                                    },
                                    "lines.*.coa_id": {
                                        "type": "integer",
                                        "description": "GL account id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "date",
                                    "lines"
                                ]
                            },
                            "example": {
                                "date": "2026-09-06",
                                "description": "Owner capital injection",
                                "lines": [
                                    {
                                        "coa_id": 3,
                                        "debit": 1000,
                                        "credit": 0,
                                        "memo": "Cash"
                                    },
                                    {
                                        "coa_id": 40,
                                        "debit": 0,
                                        "credit": 1000,
                                        "memo": "Capital"
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The created entry with lines.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/journal-entries/{id}": {
            "delete": {
                "operationId": "delete_api_accounting_v2_journal_entries_id",
                "tags": [
                    "Accounting: Journal Entries"
                ],
                "summary": "Delete a draft journal entry",
                "description": "Deletes a draft entry and its lines; posted entries cannot be deleted (`422`).",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\JournalEntriesController@destroy",
                "x-source": "app/Http/Controllers/AccountingV2/JournalEntriesController.php#L158-L172",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "journal_entries",
                        "slug": "journal_entries",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "JournalEntry",
                    "JournalEntryLine"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Entry id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Entry is posted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Posted entries cannot be deleted. Create a reversing entry instead."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_accounting_v2_journal_entries_id",
                "tags": [
                    "Accounting: Journal Entries"
                ],
                "summary": "Get a journal entry",
                "description": "The entry with its `lines`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\JournalEntriesController@show",
                "x-source": "app/Http/Controllers/AccountingV2/JournalEntriesController.php#L44-L50",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "journal_entries",
                        "slug": "journal_entries",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "JournalEntry"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Entry id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Entry object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_accounting_v2_journal_entries_id",
                "tags": [
                    "Accounting: Journal Entries"
                ],
                "summary": "Update a draft journal entry (PATCH alias)",
                "description": "Same behaviour as the PUT variant.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\JournalEntriesController@update",
                "x-source": "app/Http/Controllers/AccountingV2/JournalEntriesController.php#L117-L156",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "journal_entries",
                        "slug": "journal_entries",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "JournalEntry",
                    "JournalEntryLine"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Entry id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "lines": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "credit": {
                                                    "type": "number",
                                                    "x-laravel-rules": [
                                                        "numeric"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Credit amount."
                                                },
                                                "debit": {
                                                    "type": "number",
                                                    "x-laravel-rules": [
                                                        "numeric"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Debit amount."
                                                }
                                            }
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Full replacement list of lines."
                                    },
                                    "lines.*.coa_id": {
                                        "type": "integer",
                                        "description": "GL account id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "date",
                                    "lines"
                                ]
                            },
                            "example": {
                                "date": "2026-09-06",
                                "description": "Owner capital injection",
                                "lines": [
                                    {
                                        "coa_id": 3,
                                        "debit": 1000,
                                        "credit": 0,
                                        "memo": "Cash"
                                    },
                                    {
                                        "coa_id": 40,
                                        "debit": 0,
                                        "credit": 1000,
                                        "memo": "Capital"
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The updated entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_accounting_v2_journal_entries_id",
                "tags": [
                    "Accounting: Journal Entries"
                ],
                "summary": "Update a draft journal entry",
                "description": "Replaces date, description and all lines of a **draft** entry. Posted entries cannot be edited (`422`) — create an adjusting entry instead.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\JournalEntriesController@update",
                "x-source": "app/Http/Controllers/AccountingV2/JournalEntriesController.php#L117-L156",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "journal_entries",
                        "slug": "journal_entries",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "JournalEntry",
                    "JournalEntryLine"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Entry id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "lines": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "credit": {
                                                    "type": "number",
                                                    "x-laravel-rules": [
                                                        "numeric"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Credit amount."
                                                },
                                                "debit": {
                                                    "type": "number",
                                                    "x-laravel-rules": [
                                                        "numeric"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Debit amount."
                                                }
                                            }
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Full replacement list of lines (`coa_id, account_id, debit, credit, memo`)."
                                    },
                                    "lines.*.coa_id": {
                                        "type": "integer",
                                        "description": "GL account id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "date",
                                    "lines"
                                ]
                            },
                            "example": {
                                "date": "2026-09-06",
                                "description": "Owner capital injection",
                                "lines": [
                                    {
                                        "coa_id": 3,
                                        "debit": 1000,
                                        "credit": 0,
                                        "memo": "Cash"
                                    },
                                    {
                                        "coa_id": 40,
                                        "debit": 0,
                                        "credit": 1000,
                                        "memo": "Capital"
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The updated entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/journal-entries/{id}/post": {
            "post": {
                "operationId": "post_api_accounting_v2_journal_entries_id_post",
                "tags": [
                    "Accounting: Journal Entries"
                ],
                "summary": "Post a journal entry",
                "description": "Marks the entry `posted` (with `posted_at`) after checking that total debits equal total credits. Already posted entries are returned unchanged.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\JournalEntriesController@post",
                "x-source": "app/Http/Controllers/AccountingV2/JournalEntriesController.php#L93-L115",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "journal_entries",
                        "slug": "journal_entries",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "JournalEntry",
                    "JournalEntryLine"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Entry id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The posted entry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Entry not balanced.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Entry not balanced. Add lines so debits equal credits before posting."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/reports/balance-sheet": {
            "get": {
                "operationId": "get_api_accounting_v2_reports_balance_sheet",
                "tags": [
                    "Accounting: Reports"
                ],
                "summary": "Balance sheet",
                "description": "Totals as of `to` (default today): `assets`, `liabilities`, `equity` and `balance` (= assets − liabilities − equity, should be 0 when books are consistent).",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ReportsController@balanceSheet",
                "x-source": "app/Http/Controllers/AccountingV2/ReportsController.php#L144-L168",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "balance_sheet",
                        "slug": "balance_sheet",
                        "policy": "AccountPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "As-of date (default today)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`date`, `assets`, `liabilities`, `equity`, `balance`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "date": {},
                                        "assets": {
                                            "type": "number"
                                        },
                                        "liabilities": {
                                            "type": "number"
                                        },
                                        "equity": {
                                            "type": "number"
                                        },
                                        "balance": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/reports/profit-loss": {
            "get": {
                "operationId": "get_api_accounting_v2_reports_profit_loss",
                "tags": [
                    "Accounting: Reports"
                ],
                "summary": "Profit & loss",
                "description": "Income and expense accounts with their period amount (income = credit − debit, expense = debit − credit), zero rows excluded, plus a `summary` (`income`, `expense`, `net_profit`) computed over the whole period regardless of table filters.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ReportsController@profitAndLoss",
                "x-source": "app/Http/Controllers/AccountingV2/ReportsController.php#L72-L142",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "accounting_profit_loss",
                        "slug": "accounting_profit_loss",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date from."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date to."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`income` or `expense`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]`, `totalRows`, `summary`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/reports/tax-summary": {
            "get": {
                "operationId": "get_api_accounting_v2_reports_tax_summary",
                "tags": [
                    "Accounting: Reports"
                ],
                "summary": "Tax (VAT) summary",
                "description": "Computed from operational documents (not journals): sales and purchases that are not `pending`, with their returns. Returns the `period`, `sales`, `sale_returns`, `taxable_sales`, `output_tax`, `purchases`, `purchase_returns`, `taxable_purchases`, `input_tax` and `net_tax` (output − input).",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ReportsController@taxSummary",
                "x-source": "app/Http/Controllers/AccountingV2/ReportsController.php#L170-L265",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "accounting_tax_report",
                        "slug": "accounting_tax_report",
                        "policy": "AccountPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date from."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Tax summary object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "period": {
                                            "type": "object",
                                            "properties": {
                                                "from": {},
                                                "to": {}
                                            }
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale_returns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "taxable_sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "output_tax": {},
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchase_returns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "taxable_purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "input_tax": {},
                                        "net_tax": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounting/v2/reports/trial-balance": {
            "get": {
                "operationId": "get_api_accounting_v2_reports_trial_balance",
                "tags": [
                    "Accounting: Reports"
                ],
                "summary": "Trial balance",
                "description": "Per GL account totals of posted lines in the period: `coa_id, code, name, type, debit, credit`. Sortable by `code, name, type, debit, credit`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountingV2\\ReportsController@trialBalance",
                "x-source": "app/Http/Controllers/AccountingV2/ReportsController.php#L17-L70",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety"
                ],
                "x-permission": [
                    {
                        "ability": "trial_balance",
                        "slug": "trial_balance",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date from."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date to."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this account type."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounts": {
            "get": {
                "operationId": "get_api_accounts",
                "tags": [
                    "Accounts"
                ],
                "summary": "List accounts",
                "description": "Paginated accounts: `id, account_num, account_name, balance, note`. `search` matches number or name.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountController@index",
                "x-source": "app/Http/Controllers/AccountController.php#L13-L60",
                "x-route-name": "accounts.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "account",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Account"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`accounts[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_accounts",
                "tags": [
                    "Accounts"
                ],
                "summary": "Create an account",
                "description": "Creates an account whose `balance` starts at `initial_balance`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountController@store",
                "x-source": "app/Http/Controllers/AccountController.php#L64-L83",
                "x-route-name": "accounts.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "account",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Display name. Required."
                                    },
                                    "account_num": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Account number / code. Required."
                                    },
                                    "initial_balance": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Opening balance. Required."
                                    },
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    }
                                },
                                "required": [
                                    "account_name",
                                    "account_num",
                                    "initial_balance"
                                ]
                            },
                            "example": {
                                "account_num": "CASH-01",
                                "account_name": "Main cash",
                                "initial_balance": 500,
                                "note": "Front desk drawer"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/accounts/{account}": {
            "delete": {
                "operationId": "delete_api_accounts_account",
                "tags": [
                    "Accounts"
                ],
                "summary": "Delete an account",
                "description": "Soft-deletes the account; movements referencing it are kept.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountController@destroy",
                "x-source": "app/Http/Controllers/AccountController.php#L117-L127",
                "x-route-name": "accounts.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "account",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_accounts_account",
                "tags": [
                    "Accounts"
                ],
                "summary": "(Not implemented) Get an account",
                "description": "Empty stub; returns an empty `200`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountController@show",
                "x-source": "app/Http/Controllers/AccountController.php#L87-L91",
                "x-route-name": "accounts.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_accounts_account",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Accounts"
                ],
                "summary": "Update an account",
                "description": "Updates number, name and note. The balance is not editable here — it moves through payments, deposits, expenses and transfers.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountController@update",
                "x-source": "app/Http/Controllers/AccountController.php#L95-L113",
                "x-route-name": "accounts.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "account",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    },
                                    "account_num": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Account number. Required."
                                    },
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    }
                                },
                                "required": [
                                    "account_name",
                                    "account_num"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_accounts_account",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Accounts"
                ],
                "summary": "Update an account",
                "description": "Updates number, name and note. The balance is not editable here — it moves through payments, deposits, expenses and transfers.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountController@update",
                "x-source": "app/Http/Controllers/AccountController.php#L95-L113",
                "x-route-name": "accounts.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "account",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    },
                                    "account_num": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Account number. Required."
                                    },
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    }
                                },
                                "required": [
                                    "account_name",
                                    "account_num"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/accounts_delete_by_selection": {
            "post": {
                "operationId": "post_api_accounts_delete_by_selection",
                "tags": [
                    "Accounts"
                ],
                "summary": "Delete several accounts",
                "description": "Soft-deletes each account in `selectedIds`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "AccountController@delete_by_selection",
                "x-source": "app/Http/Controllers/AccountController.php#L131-L145",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "account",
                        "policy": "AccountPolicy"
                    }
                ],
                "x-models": [
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of account ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/adjustment_pdf/{id}": {
            "get": {
                "operationId": "get_api_adjustment_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Stock adjustment PDF",
                "description": "Streams the stock-adjustment document as a PDF: warehouse, reference, date and each line with product, variant, batch and the quantity added or subtracted. Public route (no token), intended to be opened in a new tab from the UI.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "AdjustmentController@adjustment_pdf",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L1190-L1269",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Adjustment",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Adjustment ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/adjustments": {
            "get": {
                "operationId": "get_api_adjustments",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "List stock adjustments",
                "description": "Paginated adjustments scoped to the caller's warehouses and record-view rule. Rows: `id, date (date + time), Ref, warehouse_name, items`. `search` matches `Ref` or warehouse name. Also returns the caller's `warehouses`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@index",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L29-L115",
                "x-route-name": "adjustments.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "adjustment_view",
                        "policy": "AdjustmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "warehouse_id",
                    "date"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Adjustment",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference (`LIKE`)."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on date (`YYYY-MM-DD`, exact)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`adjustments[]`, `totalRows`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "adjustments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "adjustments": [
                                        {
                                            "id": 5,
                                            "date": "2026-09-01 10:22:03",
                                            "Ref": "AD_1112",
                                            "warehouse_name": "Main",
                                            "items": 2
                                        }
                                    ],
                                    "totalRows": 1,
                                    "warehouses": [
                                        {
                                            "id": 1,
                                            "name": "Main"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_adjustments",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "Create a stock adjustment",
                "description": "Creates the adjustment and applies every line to the warehouse stock immediately: `add` increases `product_warehouse.qte`, `sub` decreases it. Combo products change the stock of their components (quantity × component quantity); the request fails validation when a combo line would exceed component stock. For batch-tracked products a line may carry `batches[]` allocations.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@store",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L119-L334",
                "x-route-name": "adjustments.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "adjustment_add",
                        "policy": "AdjustmentPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "CombinedProduct",
                    "product_warehouse",
                    "Adjustment",
                    "AdjustmentDetail"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document date (`YYYY-MM-DD`)."
                                    },
                                    "details": {
                                        "x-rules": [
                                            "custom-closure-rule"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "custom-closure-rule"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Array of lines. Required.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Warehouse being adjusted. Required."
                                    },
                                    "details.*.product_id": {
                                        "type": "integer",
                                        "description": "Product id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "details",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "warehouse_id": 1,
                                "date": "2026-09-06",
                                "notes": "Cycle count",
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 3,
                                        "type": "sub"
                                    },
                                    {
                                        "product_id": 9,
                                        "product_variant_id": 12,
                                        "quantity": 10,
                                        "type": "add"
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/adjustments/create": {
            "get": {
                "operationId": "get_api_adjustments_create",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "Get lookups for the adjustment form",
                "description": "Returns the caller's `warehouses`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@create",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L971-L985",
                "x-route-name": "adjustments.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "adjustment_add",
                        "policy": "AdjustmentPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/adjustments/detail/{id}": {
            "get": {
                "operationId": "get_api_adjustments_detail_id",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "Get adjustment details",
                "description": "Read-only view: `adjustment` header (`id, Ref, date, note, warehouse, items, created_by, created_at`) and `details[]` (`code, name, quantity, unit, type add|sub, is_batch_tracked, batches[]`).",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@Adjustment_detail",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L1119-L1186",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "adjustment_view",
                        "policy": "AdjustmentPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Adjustment",
                    "User",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Adjustment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`adjustment` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "adjustment": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/adjustments/{adjustment}": {
            "delete": {
                "operationId": "delete_api_adjustments_adjustment",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "Delete a stock adjustment",
                "description": "Reverses every line's stock effect (and batch movements) and soft-deletes the document.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@destroy",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L724-L910",
                "x-route-name": "adjustments.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "adjustment_delete",
                        "policy": "AdjustmentPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Adjustment",
                    "UserWarehouse",
                    "AdjustmentDetail",
                    "product_warehouse",
                    "Product",
                    "CombinedProduct"
                ],
                "parameters": [
                    {
                        "name": "adjustment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Adjustment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_adjustments_adjustment",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "(Not implemented) Get an adjustment",
                "description": "Resource stub with an empty body. Use `GET /api/adjustments/detail/{id}`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@show",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L338-L342",
                "x-route-name": "adjustments.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "adjustment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Adjustment id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_adjustments_adjustment",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "Update a stock adjustment",
                "description": "Reverses the stock effect of the old lines, then applies the new lines. Lines are matched by their detail `id`: existing ids are updated, missing ones deleted, new lines (`id` not in the document) inserted.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@update",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L346-L720",
                "x-route-name": "adjustments.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "adjustment_edit",
                        "policy": "AdjustmentPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Adjustment",
                    "UserWarehouse",
                    "AdjustmentDetail",
                    "product_warehouse",
                    "Product",
                    "CombinedProduct"
                ],
                "parameters": [
                    {
                        "name": "adjustment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Adjustment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines: `{id?, product_id, product_variant_id, quantity, type, batches?}`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse. Required."
                                    }
                                },
                                "required": [
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_adjustments_adjustment",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "Update a stock adjustment",
                "description": "Reverses the stock effect of the old lines, then applies the new lines. Lines are matched by their detail `id`: existing ids are updated, missing ones deleted, new lines (`id` not in the document) inserted.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@update",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L346-L720",
                "x-route-name": "adjustments.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "adjustment_edit",
                        "policy": "AdjustmentPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Adjustment",
                    "UserWarehouse",
                    "AdjustmentDetail",
                    "product_warehouse",
                    "Product",
                    "CombinedProduct"
                ],
                "parameters": [
                    {
                        "name": "adjustment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Adjustment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines: `{id?, product_id, product_variant_id, quantity, type, batches?}`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse. Required."
                                    }
                                },
                                "required": [
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/adjustments/{adjustment}/edit": {
            "get": {
                "operationId": "get_api_adjustments_adjustment_edit",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "Get an adjustment for editing",
                "description": "The adjustment in form shape (`adjustment.warehouse_id, notes, date`) with `details[]` lines (`id, detail_id, product_id, product_variant_id, code, name, quantity, current (stock now), type, unit, del, batches`) and the caller's `warehouses`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@edit",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L989-L1115",
                "x-route-name": "adjustments.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "adjustment_edit",
                        "policy": "AdjustmentPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Adjustment",
                    "UserWarehouse",
                    "Warehouse",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "adjustment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Adjustment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`adjustment`, `details[]`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "adjustment": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Document in a warehouse the caller cannot access.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/admin/products": {
            "get": {
                "operationId": "get_api_admin_products",
                "tags": [
                    "Store Collections"
                ],
                "summary": "Search products (alias)",
                "description": "Same as `/api/admin/store/products`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@searchProducts",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L309-L329",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Max rows."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name, code or id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`[{id, name, code}]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/admin/store/collections": {
            "get": {
                "operationId": "get_api_admin_store_collections",
                "tags": [
                    "Store Collections"
                ],
                "summary": "List collections",
                "description": "All collections with `products_count`, ordered by `sort_order`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@index",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L15-L36",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "x-models": [
                    "Collection"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Title or slug."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of collections.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_admin_store_collections",
                "tags": [
                    "Store Collections"
                ],
                "summary": "Create a collection",
                "description": "Also inserts a `collection` block into the homepage lineup. `limit` defaults to 8, `sort_order` to max + 10.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@store",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L50-L115",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "x-models": [
                    "Collection",
                    "StoreSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Max products shown on the home block."
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "collections,slug",
                                        "x-rules": [
                                            "alpha_dash"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190",
                                            "alpha_dash",
                                            "unique:collections,slug"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unique slug (alpha-dash)."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "slug",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The collection.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/admin/store/collections/{collection}": {
            "delete": {
                "operationId": "delete_api_admin_store_collections_collection",
                "tags": [
                    "Store Collections"
                ],
                "summary": "Delete a collection",
                "description": "Detaches products and removes the block from the homepage lineup.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L228-L265",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting"
                ],
                "parameters": [
                    {
                        "name": "collection",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Collection id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_admin_store_collections_collection",
                "tags": [
                    "Store Collections"
                ],
                "summary": "Get a collection",
                "description": "With its `products[]` (pivot `sort_order`, `pinned`).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@show",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L39-L48",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "collection",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Collection id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Collection object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_admin_store_collections_collection",
                "tags": [
                    "Store Collections"
                ],
                "summary": "Update a collection",
                "description": "Partial update; a slug change is propagated to the homepage lineup.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@update",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L118-L224",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting"
                ],
                "parameters": [
                    {
                        "name": "collection",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Collection id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Limit."
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "collections,slug ->ignore",
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-rules": [
                                            "alpha_dash"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "string",
                                            "max:190",
                                            "alpha_dash",
                                            "unique:collections,slug ->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Slug."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "The collection.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/admin/store/collections/{collection}/products": {
            "post": {
                "operationId": "post_api_admin_store_collections_collection_products",
                "tags": [
                    "Store Collections"
                ],
                "summary": "Set the products of a collection",
                "description": "Full sync: the `items` list becomes the collection content.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@syncProducts",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L272-L306",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "collection",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Collection id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "pinned": {
                                                    "type": "boolean",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "boolean"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Pin to the top."
                                                },
                                                "product_id": {
                                                    "type": "integer",
                                                    "x-exists": "products,id",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer",
                                                        "exists:products,id"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product."
                                                },
                                                "sort_order": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Order (default position × 10)."
                                                }
                                            },
                                            "required": [
                                                "product_id"
                                            ]
                                        },
                                        "x-laravel-rules": [
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Products."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "The collection with products.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/admin/store/menus": {
            "get": {
                "operationId": "get_api_admin_store_menus",
                "tags": [
                    "Store Settings"
                ],
                "summary": "Get storefront menus",
                "description": "Normalised `menus` (header / footer link trees) plus link targets: `pages`, `collections`, and `locales`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SettingsApiController@menus",
                "x-source": "app/Http/Controllers/Api/Store/SettingsApiController.php#L619-L638",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting",
                    "StorePage",
                    "Collection"
                ],
                "responses": {
                    "200": {
                        "description": "`menus`, `pages[]`, `collections[]`, `locales`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "menus": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "pages": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "collections": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "locales": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_admin_store_menus",
                "tags": [
                    "Store Settings"
                ],
                "summary": "Save storefront menus",
                "description": "Persist the storefront menus. /",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SettingsApiController@updateMenus",
                "x-source": "app/Http/Controllers/Api/Store/SettingsApiController.php#L643-L655",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "menus": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Menu structure (object keyed by menu name, each an array of `{label, label_translations, type, target, url, children[]}`).",
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Normalised `menus`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "menus": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/admin/store/products": {
            "get": {
                "operationId": "get_api_admin_store_products",
                "tags": [
                    "Store Collections"
                ],
                "summary": "Search products for collections",
                "description": "Lightweight product search used when composing a collection: matches name or code and returns `id`, `name`, `code`, `price` and image for the picker. Not paginated; limited to the first matches.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\CollectionController@searchProducts",
                "x-source": "app/Http/Controllers/Api/Store/CollectionController.php#L309-L329",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Collections_view",
                        "policy": "CollectionPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Max rows (default 20, max 50)."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name, code or id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`[{id, name, code}]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/admin/store/settings": {
            "get": {
                "operationId": "get_api_admin_store_settings",
                "tags": [
                    "Store Settings"
                ],
                "summary": "Get store settings",
                "description": "The full `settings` object (defaults are created on first call), plus `warehouses`, `currencies`, `pending_customers_count` and `curated_products` for the homepage editor.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SettingsApiController@show",
                "x-source": "app/Http/Controllers/Api/Store/SettingsApiController.php#L22-L135",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting",
                    "Setting",
                    "Warehouse",
                    "Currency",
                    "EcommerceClient",
                    "Product"
                ],
                "responses": {
                    "200": {
                        "description": "`settings`, `warehouses[]`, `currencies[]`, `pending_customers_count`, `curated_products[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "currencies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "pending_customers_count": {
                                            "type": "integer"
                                        },
                                        "curated_products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_admin_store_settings",
                "tags": [
                    "Store Settings"
                ],
                "summary": "Save store settings",
                "description": "Multipart. Only the fields sent are updated; booleans accept `0/1` or `true/false`. Image fields (`logo`, `favicon`, `hero_image`, `gcash_qr`) replace the stored file. Secrets left empty keep their current value. Field groups: **general** (`enabled`, `store_name`, `store_domain`, `store_url_path`, `store_use_root_domain`, `language`, `default_currency_id`, `display_currency_id`), **catalogue** (`default_warehouse_id`, `store_all_warehouses`, `warehouse_ids[]`, `allow_overselling`, `hide_out_of_stock`, `hide_prices_for_guests`, `show_stock`), **appearance** (`theme` default|real_estate|electronics|toys|grocery, `theme_options`, `primary_color`, `secondary_color`, `font_family`, `hero_*`, `topbar_text_*`, `footer_text`, `homepage_layout`, `homepage_lineup`, `custom_css`, `custom_js`, `text_translations`, `social_links`), **customers** (`registration_enabled`, `require_invite_code`, `require_admin_approval`, `require_email_verification`, `allow_cancellations`, `return_window_days`, `auto_approve_reviews`, `cookie_consent_enabled`), **contact** (`contact_*`), **SEO** (`seo_*`), **payments** (`payment_*_enabled`, PayPal / Paystack / Flutterwave / Razorpay / bKash / SSLCommerz credentials, bank and GCash details, `pickup_instructions`), **wallet** (`wallet_*`).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SettingsApiController@update",
                "x-source": "app/Http/Controllers/Api/Store/SettingsApiController.php#L140-L614",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "StoreSetting",
                    "Currency",
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "allow_cancellations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Let shoppers cancel orders that are still pending.",
                                        "type": "boolean"
                                    },
                                    "allow_overselling": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Accept orders for quantities above stock.",
                                        "type": "boolean"
                                    },
                                    "auto_approve_reviews": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Publish product reviews without moderation.",
                                        "type": "boolean"
                                    },
                                    "bank_account_name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account holder name."
                                    },
                                    "bank_account_number": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account number / IBAN."
                                    },
                                    "bank_branch": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Branch / SWIFT information."
                                    },
                                    "bank_instructions": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Instructions shown to the shopper after choosing bank transfer."
                                    },
                                    "bank_name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bank name shown for bank transfers."
                                    },
                                    "bkash_app_key": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "bKash app key."
                                    },
                                    "bkash_app_secret": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "bKash app secret (write-only)."
                                    },
                                    "bkash_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable bKash checkout.",
                                        "type": "boolean"
                                    },
                                    "bkash_password": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "bKash merchant password (write-only)."
                                    },
                                    "bkash_sandbox": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Use the bKash sandbox.",
                                        "type": "boolean"
                                    },
                                    "bkash_username": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "bKash merchant username."
                                    },
                                    "contact_address": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Postal address shown on the store."
                                    },
                                    "contact_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Contact email shown on the store."
                                    },
                                    "contact_phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Contact phone shown on the store."
                                    },
                                    "cookie_consent_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show the cookie-consent banner.",
                                        "type": "boolean"
                                    },
                                    "custom_css": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Extra CSS injected into every storefront page."
                                    },
                                    "custom_js": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Extra JavaScript injected into every storefront page (analytics, chat widgets)."
                                    },
                                    "default_currency_id": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Currency orders are recorded in (base currency).",
                                        "type": "integer"
                                    },
                                    "default_warehouse_id": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse that fulfils online orders and whose stock is shown.",
                                        "type": "integer"
                                    },
                                    "display_currency_id": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Currency shown to shoppers when different from the base currency (converted with the stored rate).",
                                        "type": "integer"
                                    },
                                    "enabled": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "0",
                                            "1"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Storefront on/off."
                                    },
                                    "favicon": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp,ico",
                                            "mimetypes:image/png,image/jpeg,image/webp,image/x-icon,image/vnd.microsoft.icon",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Storefront favicon (multipart).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "flutterwave_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable Flutterwave checkout.",
                                        "type": "boolean"
                                    },
                                    "flutterwave_public_key": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Flutterwave public key."
                                    },
                                    "flutterwave_secret_hash": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Hash used to verify Flutterwave webhooks."
                                    },
                                    "flutterwave_secret_key": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Flutterwave secret key (write-only)."
                                    },
                                    "font_family": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Google/system font family used by the theme."
                                    },
                                    "footer_text": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Footer text / copyright line."
                                    },
                                    "gcash_account_name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "GCash account name."
                                    },
                                    "gcash_account_number": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "GCash account number."
                                    },
                                    "gcash_instructions": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Instructions shown for GCash payments."
                                    },
                                    "gcash_qr": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "GCash QR code image (multipart).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "hero_image": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:8192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Hero background image (multipart).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "hero_subtitle": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sub-headline of the hero."
                                    },
                                    "hero_title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Headline of the home page hero."
                                    },
                                    "hide_out_of_stock": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Hide products whose stock is zero.",
                                        "type": "boolean"
                                    },
                                    "hide_prices_for_guests": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Hide prices until the shopper logs in (B2B mode).",
                                        "type": "boolean"
                                    },
                                    "home_collections": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Collection IDs featured on the home page, in order (array or JSON).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "homepage_layout": {
                                        "type": "string",
                                        "enum": [
                                            "default"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "in:default"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Home page layout preset."
                                    },
                                    "homepage_lineup": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "JSON array of homepage blocks.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "language": {
                                        "type": "string",
                                        "maxLength": 10,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:10"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default storefront locale."
                                    },
                                    "logo": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Storefront logo image (multipart).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "payment_bank_transfer_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable manual bank transfer (shopper uploads a payment proof).",
                                        "type": "boolean"
                                    },
                                    "payment_cash_on_pickup_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable pay-at-pickup.",
                                        "type": "boolean"
                                    },
                                    "payment_cod_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable cash on delivery.",
                                        "type": "boolean"
                                    },
                                    "payment_gcash_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable GCash manual payment.",
                                        "type": "boolean"
                                    },
                                    "payment_mobile_money_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable generic mobile-money manual payment.",
                                        "type": "boolean"
                                    },
                                    "payment_stripe_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable Stripe card payments (keys are configured under Payment Gateway settings).",
                                        "type": "boolean"
                                    },
                                    "paypal_client_id": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "PayPal REST client ID."
                                    },
                                    "paypal_client_secret": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "PayPal REST client secret (write-only)."
                                    },
                                    "paypal_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable PayPal checkout.",
                                        "type": "boolean"
                                    },
                                    "paypal_test_mode": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Use the PayPal sandbox.",
                                        "type": "boolean"
                                    },
                                    "paypal_webhook_id": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "PayPal webhook ID used to verify notifications."
                                    },
                                    "paystack_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable Paystack checkout.",
                                        "type": "boolean"
                                    },
                                    "paystack_public_key": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Paystack public key."
                                    },
                                    "paystack_secret_key": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Paystack secret key (write-only)."
                                    },
                                    "pickup_instructions": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Text shown when the shopper chooses in-store pickup."
                                    },
                                    "primary_color": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Primary theme colour (hex)."
                                    },
                                    "razorpay_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable Razorpay checkout.",
                                        "type": "boolean"
                                    },
                                    "razorpay_key_id": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Razorpay key ID."
                                    },
                                    "razorpay_key_secret": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Razorpay key secret (write-only)."
                                    },
                                    "razorpay_webhook_secret": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Secret used to verify Razorpay webhooks."
                                    },
                                    "registration_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Allow new shopper registrations.",
                                        "type": "boolean"
                                    },
                                    "require_admin_approval": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "New registrations wait in *Pending customers* until approved.",
                                        "type": "boolean"
                                    },
                                    "require_email_verification": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Shoppers must verify their email before ordering.",
                                        "type": "boolean"
                                    },
                                    "require_invite_code": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Registration requires a valid invite code.",
                                        "type": "boolean"
                                    },
                                    "return_window_days": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:365"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Days after delivery during which a return request can be filed.",
                                        "type": "integer"
                                    },
                                    "secondary_color": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Secondary theme colour (hex)."
                                    },
                                    "seo_meta_description": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default meta description."
                                    },
                                    "seo_meta_title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default `<title>` of storefront pages."
                                    },
                                    "seo_title_template": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title pattern for product/category pages, e.g. `%s | My Store`."
                                    },
                                    "show_stock": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Show stock quantity on product pages.",
                                        "type": "boolean"
                                    },
                                    "social_links": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "JSON of social URLs.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "sslcommerz_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable SSLCommerz checkout.",
                                        "type": "boolean"
                                    },
                                    "sslcommerz_sandbox": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Use the SSLCommerz sandbox.",
                                        "type": "boolean"
                                    },
                                    "sslcommerz_store_id": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SSLCommerz store ID."
                                    },
                                    "sslcommerz_store_password": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SSLCommerz store password (write-only)."
                                    },
                                    "store_all_warehouses": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Show combined stock of all warehouses instead of only the default warehouse.",
                                        "type": "boolean"
                                    },
                                    "store_domain": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Custom domain the storefront answers on (empty = same host as the admin)."
                                    },
                                    "store_name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Store name."
                                    },
                                    "store_url_path": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "URL prefix of the storefront (default `online_store`)."
                                    },
                                    "store_use_root_domain": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Serve the storefront at the root of `store_domain` instead of under `store_url_path`.",
                                        "type": "boolean"
                                    },
                                    "text_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "JSON of UI text overrides per locale.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "theme": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'nullable|string|in:default,real_estate,' . implode(',', \\App\\Support\\StoreThemes::SKINS)"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'nullable|string|in:default,real_estate,' . implode(',', \\App\\Support\\StoreThemes::SKINS)"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Theme key."
                                    },
                                    "theme_options": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "JSON theme options.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "topbar_text_left": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Announcement text on the left of the top bar."
                                    },
                                    "topbar_text_right": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Announcement text on the right of the top bar."
                                    },
                                    "wallet_allow_negative": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Allow the wallet balance to go negative (credit line).",
                                        "type": "boolean"
                                    },
                                    "wallet_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable the shopper wallet (store credit).",
                                        "type": "boolean"
                                    },
                                    "wallet_min_withdrawal": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Minimum amount for a withdrawal request.",
                                        "type": "number"
                                    },
                                    "wallet_refund_destination": {
                                        "type": "string",
                                        "enum": [
                                            "wallet",
                                            "original"
                                        ],
                                        "description": "Default refund destination.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "wallet_withdrawal_enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Let shoppers request withdrawals of their wallet balance.",
                                        "type": "boolean"
                                    },
                                    "warehouse_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouses feeding the store when not all.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "The updated `settings`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_assignments": {
            "get": {
                "operationId": "get_api_asset_assignments",
                "tags": [
                    "Asset Assignments"
                ],
                "summary": "List assignments",
                "description": "Paginated with asset name/tag and holder name. Sortable: `id, assigned_on, due_back_on, returned_on, status, asset_name, asset_tag, user_name`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetAssignmentController@index",
                "x-source": "app/Http/Controllers/AssetAssignmentController.php#L21-L108",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "AssetAssignmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AssetAssignment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "asset_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Asset filter."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`assigned` or `returned`."
                    },
                    {
                        "name": "user_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Holder filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`assignments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "assignments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_asset_assignments",
                "tags": [
                    "Asset Assignments"
                ],
                "summary": "Check out an asset",
                "description": "Creates an open assignment and sets the asset's `assigned_to_id`. Refused (`422`) if the asset is disposed or already checked out.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetAssignmentController@store",
                "x-source": "app/Http/Controllers/AssetAssignmentController.php#L110-L160",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "AssetAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "Asset",
                    "AssetAssignment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "asset_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "assets,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:assets,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Asset."
                                    },
                                    "assigned_on": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Check-out date."
                                    },
                                    "condition_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Condition at check-out."
                                    },
                                    "due_back_on": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:assigned_on"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:assigned_on"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Expected return (>= assigned_on)."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "user_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "users,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:users,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Holder user."
                                    }
                                },
                                "required": [
                                    "asset_id",
                                    "assigned_on",
                                    "user_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Asset not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Asset not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_assignments/delete/by_selection": {
            "post": {
                "operationId": "post_api_asset_assignments_delete_by_selection",
                "tags": [
                    "Asset Assignments"
                ],
                "summary": "Delete selected assignments",
                "description": "Bulk delete. Pass `selectedIds` (array of assignment IDs); each assignment is soft-deleted and the asset is marked as unassigned again.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetAssignmentController@deleteBySelection",
                "x-source": "app/Http/Controllers/AssetAssignmentController.php#L247-L268",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AssetAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "AssetAssignment",
                    "Asset"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Assignment ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_assignments/{id}": {
            "delete": {
                "operationId": "delete_api_asset_assignments_id",
                "tags": [
                    "Asset Assignments"
                ],
                "summary": "Delete an assignment",
                "description": "Deleting an open assignment also releases the asset.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetAssignmentController@destroy",
                "x-source": "app/Http/Controllers/AssetAssignmentController.php#L225-L245",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AssetAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "AssetAssignment",
                    "Asset"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Assignment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_asset_assignments_id",
                "tags": [
                    "Asset Assignments"
                ],
                "summary": "Update assignment paperwork",
                "description": "Only dates, condition and notes are editable; asset and holder change through check-out / check-in.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetAssignmentController@update",
                "x-source": "app/Http/Controllers/AssetAssignmentController.php#L162-L183",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AssetAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "AssetAssignment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Assignment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_on": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Check-out date."
                                    },
                                    "condition_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Condition."
                                    },
                                    "due_back_on": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:assigned_on"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:assigned_on"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due back."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    }
                                },
                                "required": [
                                    "assigned_on"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_assignments/{id}/checkin": {
            "post": {
                "operationId": "post_api_asset_assignments_id_checkin",
                "tags": [
                    "Asset Assignments"
                ],
                "summary": "Check in an asset",
                "description": "Closes the assignment (`returned`) and clears the asset's holder.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetAssignmentController@checkin",
                "x-source": "app/Http/Controllers/AssetAssignmentController.php#L186-L223",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AssetAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "AssetAssignment",
                    "Asset"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Assignment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "condition_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Condition at return."
                                    },
                                    "returned_on": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Return date (>= assigned_on)."
                                    }
                                },
                                "required": [
                                    "returned_on"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_maintenances": {
            "get": {
                "operationId": "get_api_asset_maintenances",
                "tags": [
                    "Asset Maintenance"
                ],
                "summary": "List maintenance jobs",
                "description": "Paginated with asset name/tag and `totals` (cost). Sortable: `id, title, type, status, cost, scheduled_date, completed_date, next_due_date, asset_name, asset_tag`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetMaintenanceController@index",
                "x-source": "app/Http/Controllers/AssetMaintenanceController.php#L24-L109",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "AssetMaintenancePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AssetMaintenance"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "asset_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Asset filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled from."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled to."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Maintenance type."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`maintenances[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "maintenances": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "cost": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_asset_maintenances",
                "tags": [
                    "Asset Maintenance"
                ],
                "summary": "Create a maintenance job",
                "description": "Default status `scheduled`. A `completed` job gets today's `completed_date` when none is given. The asset's status is synced (open job → `maintenance`).",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetMaintenanceController@store",
                "x-source": "app/Http/Controllers/AssetMaintenanceController.php#L111-L149",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "AssetMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "AssetMaintenance"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "asset_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "assets,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:assets,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Asset."
                                    },
                                    "completed_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Completion date (>= scheduled)."
                                    },
                                    "cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cost."
                                    },
                                    "next_due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Next maintenance due."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "scheduled_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Planned date."
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "in_progress",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "description": "Status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 191)."
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "service",
                                            "repair",
                                            "inspection",
                                            "calibration",
                                            "upgrade",
                                            "other"
                                        ],
                                        "description": "Maintenance type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "vendor": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Service provider."
                                    }
                                },
                                "required": [
                                    "asset_id",
                                    "scheduled_date",
                                    "title",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_maintenances/delete/by_selection": {
            "post": {
                "operationId": "post_api_asset_maintenances_delete_by_selection",
                "tags": [
                    "Asset Maintenance"
                ],
                "summary": "Delete selected maintenance jobs",
                "description": "Bulk delete of maintenance jobs by `selectedIds`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetMaintenanceController@deleteBySelection",
                "x-source": "app/Http/Controllers/AssetMaintenanceController.php#L229-L242",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AssetMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "AssetMaintenance"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Maintenance ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_maintenances/{id}": {
            "delete": {
                "operationId": "delete_api_asset_maintenances_id",
                "tags": [
                    "Asset Maintenance"
                ],
                "summary": "Delete a maintenance job",
                "description": "Soft-deletes a maintenance job. If it was the job that put the asset under maintenance, the asset status is not changed automatically — update the asset separately.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetMaintenanceController@destroy",
                "x-source": "app/Http/Controllers/AssetMaintenanceController.php#L218-L227",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AssetMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "AssetMaintenance"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Maintenance id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_asset_maintenances_id",
                "tags": [
                    "Asset Maintenance"
                ],
                "summary": "Update a maintenance job",
                "description": "Updates a maintenance job with the same fields and validation as creation. Setting `status` to `completed` stores the completion date and cost.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetMaintenanceController@update",
                "x-source": "app/Http/Controllers/AssetMaintenanceController.php#L151-L191",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AssetMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "AssetMaintenance"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Maintenance id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "completed_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Completion date."
                                    },
                                    "cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cost."
                                    },
                                    "next_due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Next due."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "scheduled_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Planned date."
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "in_progress",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "description": "Status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "service",
                                            "repair",
                                            "inspection",
                                            "calibration",
                                            "upgrade",
                                            "other"
                                        ],
                                        "description": "Type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "vendor": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Vendor."
                                    }
                                },
                                "required": [
                                    "scheduled_date",
                                    "title",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_maintenances/{id}/status": {
            "post": {
                "operationId": "post_api_asset_maintenances_id_status",
                "tags": [
                    "Asset Maintenance"
                ],
                "summary": "Quick status change",
                "description": "Quick status change from the list, without opening the form.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetMaintenanceController@setStatus",
                "x-source": "app/Http/Controllers/AssetMaintenanceController.php#L194-L216",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AssetMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "AssetMaintenance"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Maintenance id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "in_progress",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "description": "New status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_transfers": {
            "get": {
                "operationId": "get_api_asset_transfers",
                "tags": [
                    "Asset Transfers"
                ],
                "summary": "List transfers",
                "description": "Paginated with asset and both warehouse names. Sortable: `id, transfer_date, asset_name, asset_tag, from_warehouse_name, to_warehouse_name`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetTransferController@index",
                "x-source": "app/Http/Controllers/AssetTransferController.php#L20-L103",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "AssetTransferPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AssetTransfer"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "asset_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Asset filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Transfer date from."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Transfer date to."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Either end matches this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`transfers[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "transfers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_asset_transfers",
                "tags": [
                    "Asset Transfers"
                ],
                "summary": "Transfer an asset",
                "description": "Moves the asset to `to_warehouse_id` and records the transfer. Refused when the destination equals the current warehouse or either warehouse is not accessible.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetTransferController@store",
                "x-source": "app/Http/Controllers/AssetTransferController.php#L105-L150",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "AssetTransferPolicy"
                    }
                ],
                "x-models": [
                    "Asset",
                    "AssetTransfer"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "asset_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "assets,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:assets,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Asset."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason."
                                    },
                                    "to_warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Destination warehouse."
                                    },
                                    "transfer_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    }
                                },
                                "required": [
                                    "asset_id",
                                    "to_warehouse_id",
                                    "transfer_date"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Asset not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Asset not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_transfers/delete/by_selection": {
            "post": {
                "operationId": "post_api_asset_transfers_delete_by_selection",
                "tags": [
                    "Asset Transfers"
                ],
                "summary": "Undo selected transfers",
                "description": "Processed newest first so the asset walks back along the chain.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetTransferController@deleteBySelection",
                "x-source": "app/Http/Controllers/AssetTransferController.php#L165-L186",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AssetTransferPolicy"
                    }
                ],
                "x-models": [
                    "AssetTransfer"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Transfer ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/asset_transfers/{id}": {
            "delete": {
                "operationId": "delete_api_asset_transfers_id",
                "tags": [
                    "Asset Transfers"
                ],
                "summary": "Undo a transfer",
                "description": "Deletes the record and moves the asset back to the source warehouse.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetTransferController@destroy",
                "x-source": "app/Http/Controllers/AssetTransferController.php#L152-L163",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AssetTransferPolicy"
                    }
                ],
                "x-models": [
                    "AssetTransfer"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Transfer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets": {
            "get": {
                "operationId": "get_api_assets",
                "tags": [
                    "Assets"
                ],
                "summary": "List assets",
                "description": "Paginated assets with `warehouse_name` and `asset_category_name`. Sortable: `id, name, tag, serial_number, status, purchase_date, purchase_cost, last_verification, next_validation, warehouse_name, asset_category_name`. `search` matches name, tag, serial or category.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@index",
                "x-source": "app/Http/Controllers/AssetController.php#L16-L97",
                "x-route-name": "assets.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Asset"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`assets[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "assets": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_assets",
                "tags": [
                    "Assets"
                ],
                "summary": "Create an asset",
                "description": "Registers a fixed asset: identification (name, code, serial), category, purchase date/cost, depreciation settings, current location/holder and an optional image. The asset starts in the `available` status unless another is given.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@store",
                "x-source": "app/Http/Controllers/AssetController.php#L128-L163",
                "x-route-name": "assets.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "asset_category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "asset_categories,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:asset_categories,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Category."
                                    },
                                    "assigned_to_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Holder user id."
                                    },
                                    "depreciation_method": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "none",
                                            "straight_line",
                                            "declining_balance"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:none,straight_line,declining_balance"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`none`, `straight_line`, `declining_balance`."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "last_verification": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Last physical check date.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "next_validation": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Next check due date.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "purchase_cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cost."
                                    },
                                    "purchase_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase date."
                                    },
                                    "salvage_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-rules": [
                                            "lte:purchase_cost"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "lte:purchase_cost"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Residual value (<= purchase cost)."
                                    },
                                    "serial_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Serial."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Status (e.g. `available`, `in_use`)."
                                    },
                                    "supplier": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Supplier name."
                                    },
                                    "tag": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-unique": "assets,tag",
                                        "x-laravel-rules": [
                                            "required",
                                            "unique:assets,tag"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unique asset tag."
                                    },
                                    "useful_life_months": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 1200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:1200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Useful life 1–1200 months."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Home warehouse."
                                    },
                                    "warranty_expiry": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty end date.",
                                        "type": "string",
                                        "format": "date"
                                    }
                                },
                                "required": [
                                    "name",
                                    "tag"
                                ]
                            },
                            "example": {
                                "tag": "LAP-0042",
                                "name": "Dell Latitude 5440",
                                "asset_category_id": 2,
                                "serial_number": "5CG1234ABC",
                                "purchase_date": "2026-01-15",
                                "purchase_cost": 1200,
                                "supplier": "Dell",
                                "warranty_expiry": "2029-01-15",
                                "depreciation_method": "straight_line",
                                "useful_life_months": 36,
                                "salvage_value": 100,
                                "status": "in_use",
                                "warehouse_id": 1,
                                "next_validation": "2026-12-31"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/create": {
            "get": {
                "operationId": "get_api_assets_create",
                "tags": [
                    "Assets"
                ],
                "summary": "Create-form data for an asset",
                "description": "Lookup data for the asset form: categories, warehouses/locations, employees and users that can hold an asset. No side effects.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@create",
                "x-source": "app/Http/Controllers/AssetController.php#L228-L255",
                "x-route-name": "assets.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "AssetCategory"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]` (caller's) and `asset_categories[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "asset_categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/delete/by_selection": {
            "post": {
                "operationId": "post_api_assets_delete_by_selection",
                "tags": [
                    "Assets"
                ],
                "summary": "Delete selected assets",
                "description": "Bulk soft-delete of assets by `selectedIds`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@delete_by_selection",
                "x-source": "app/Http/Controllers/AssetController.php#L215-L225",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Asset ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/due": {
            "get": {
                "operationId": "get_api_assets_due",
                "tags": [
                    "Assets"
                ],
                "summary": "Assets due for validation",
                "description": "Assets whose `next_validation` falls within the next 5 working days (or is overdue), soonest first.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@due",
                "x-source": "app/Http/Controllers/AssetController.php#L327-L368",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset"
                ],
                "responses": {
                    "200": {
                        "description": "`assets[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "assets": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/run-validation-due": {
            "post": {
                "operationId": "post_api_assets_run_validation_due",
                "tags": [
                    "Assets"
                ],
                "summary": "Run the validation-due check now",
                "description": "Runs `assets:check-validation-due` synchronously and returns its output. Sends email / in-app notifications for due assets.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@runValidationDue",
                "x-source": "app/Http/Controllers/AssetController.php#L411-L422",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/schedule-info": {
            "get": {
                "operationId": "get_api_assets_schedule_info",
                "tags": [
                    "Assets"
                ],
                "summary": "Validation scheduler info",
                "description": "The cron line to install, the artisan command (`assets:check-validation-due`) and its schedule.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@scheduleInfo",
                "x-source": "app/Http/Controllers/AssetController.php#L394-L408",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`cron_line`, `base_path`, `command`, `schedule`, `description`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "cron_line": {},
                                        "base_path": {},
                                        "command": {
                                            "type": "string",
                                            "example": "assets:check-validation-due"
                                        },
                                        "schedule": {
                                            "type": "string",
                                            "example": "daily"
                                        },
                                        "description": {
                                            "type": "string",
                                            "example": "Runs once per day. Finds assets whose next validation date is within 5 working days (or overdue) and sends email + in-app notifications to users with Assets permission."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/workspace/dashboard": {
            "get": {
                "operationId": "get_api_assets_workspace_dashboard",
                "tags": [
                    "Asset Workspace"
                ],
                "summary": "Asset dashboard",
                "description": "Counts (`total`, `in_use`, `maintenance`, `retired`, `unassigned`), values (`purchase_value`, `book_value`, `depreciation_to_date`, `maintenance_ytd`), due / overdue validations, open / overdue maintenance, overdue returns, breakdowns `by_category`, `by_status`, `by_warehouse`, a 12-month `spend_trend`, `upcoming_validations`, `open_jobs` and `recent` activity.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetWorkspaceController@dashboard",
                "x-source": "app/Http/Controllers/AssetWorkspaceController.php#L29-L239",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset",
                    "AssetMaintenance",
                    "AssetAssignment"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "in_use": {
                                            "type": "integer"
                                        },
                                        "maintenance": {
                                            "type": "integer"
                                        },
                                        "retired": {
                                            "type": "integer"
                                        },
                                        "unassigned": {
                                            "type": "integer"
                                        },
                                        "assigned": {},
                                        "purchase_value": {
                                            "type": "number"
                                        },
                                        "book_value": {
                                            "type": "number"
                                        },
                                        "depreciation_to_date": {
                                            "type": "number"
                                        },
                                        "due_validation": {},
                                        "overdue_validation": {},
                                        "open_maintenance": {},
                                        "overdue_maintenance": {},
                                        "overdue_returns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "maintenance_ytd": {
                                            "type": "number"
                                        },
                                        "by_category": {},
                                        "by_status": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_warehouse": {},
                                        "spend_trend": {},
                                        "upcoming_validations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "overdue_returns_rows": {
                                            "type": "integer"
                                        },
                                        "open_jobs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recent": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/workspace/details/{id}": {
            "get": {
                "operationId": "get_api_assets_workspace_details_id",
                "tags": [
                    "Asset Workspace"
                ],
                "summary": "Asset details page",
                "description": "The `asset` with category, warehouse and holder names, its depreciation `schedule`, and history lists `maintenance[]`, `assignments[]`, `transfers[]`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetWorkspaceController@details",
                "x-source": "app/Http/Controllers/AssetWorkspaceController.php#L282-L391",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset",
                    "AssetMaintenance",
                    "AssetAssignment",
                    "AssetTransfer"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Asset id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`asset`, `schedule`, `maintenance[]`, `assignments[]`, `transfers[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "asset": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "tag": {},
                                                "name": {},
                                                "serial_number": {},
                                                "description": {},
                                                "status": {},
                                                "category_name": {},
                                                "warehouse_name": {},
                                                "holder_name": {},
                                                "supplier": {},
                                                "purchase_date": {},
                                                "purchase_cost": {
                                                    "type": "number"
                                                },
                                                "warranty_expiry": {
                                                    "type": "string"
                                                },
                                                "under_warranty": {},
                                                "last_verification": {
                                                    "type": "string"
                                                },
                                                "next_validation": {
                                                    "type": "string"
                                                },
                                                "days_to_validation": {},
                                                "depreciation_method": {},
                                                "useful_life_months": {},
                                                "salvage_value": {
                                                    "type": "number"
                                                },
                                                "accumulated_depreciation": {},
                                                "book_value": {},
                                                "disposal_date": {
                                                    "type": "string"
                                                },
                                                "disposal_amount": {
                                                    "type": "number"
                                                },
                                                "disposal_note": {},
                                                "disposal_gain": {},
                                                "total_cost_of_ownership": {
                                                    "type": "number"
                                                },
                                                "maintenance_cost": {
                                                    "type": "number"
                                                }
                                            }
                                        },
                                        "schedule": {},
                                        "maintenance": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "assignments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "transfers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/workspace/dispose/{id}": {
            "post": {
                "operationId": "post_api_assets_workspace_dispose_id",
                "tags": [
                    "Asset Workspace"
                ],
                "summary": "Dispose of an asset",
                "description": "Retires the asset: freezes depreciation at `disposal_date`, records the sale amount and the gain/loss versus book value, sets status `retired`. Refused if already disposed, if the date precedes purchase, or while someone still holds it.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetWorkspaceController@dispose",
                "x-source": "app/Http/Controllers/AssetWorkspaceController.php#L397-L448",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset",
                    "AssetAssignment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Asset id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "disposal_amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount received."
                                    },
                                    "disposal_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Disposal date."
                                    },
                                    "disposal_note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Note."
                                    }
                                },
                                "required": [
                                    "disposal_date"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `book_value`, `gain`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "book_value": {},
                                        "gain": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/workspace/meta": {
            "get": {
                "operationId": "get_api_assets_workspace_meta",
                "tags": [
                    "Asset Workspace"
                ],
                "summary": "Workspace lookups",
                "description": "`warehouses` (caller's), `categories`, live `assets` (`id, name, tag, label, warehouse_id, assigned_to_id`) and `users`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetWorkspaceController@meta",
                "x-source": "app/Http/Controllers/AssetWorkspaceController.php#L244-L277",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "AssetCategory",
                    "Asset",
                    "User"
                ],
                "responses": {
                    "200": {
                        "description": "Lookup lists.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "assets": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "users": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/workspace/report/custody": {
            "get": {
                "operationId": "get_api_assets_workspace_report_custody",
                "tags": [
                    "Asset Workspace"
                ],
                "summary": "Custody report",
                "description": "Per holder: assignments `total`, currently `holding`, `returned`, `overdue`, `returned_late` and `on_time_rate`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetWorkspaceController@custodyReport",
                "x-source": "app/Http/Controllers/AssetWorkspaceController.php#L599-L648",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "AssetAssignment"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Assigned from."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Assigned to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "user_name": {},
                                        "total": {
                                            "type": "integer"
                                        },
                                        "holding": {
                                            "type": "integer"
                                        },
                                        "returned": {},
                                        "overdue": {
                                            "type": "integer"
                                        },
                                        "returned_late": {},
                                        "on_time_rate": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "holding": {
                                                    "type": "integer"
                                                },
                                                "overdue": {
                                                    "type": "integer"
                                                },
                                                "returned": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/workspace/report/maintenance": {
            "get": {
                "operationId": "get_api_assets_workspace_report_maintenance",
                "tags": [
                    "Asset Workspace"
                ],
                "summary": "Maintenance spend report",
                "description": "Per asset: number of jobs, completed, open, `spend` and `spend_ratio` (spend / purchase cost).",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetWorkspaceController@maintenanceReport",
                "x-source": "app/Http/Controllers/AssetWorkspaceController.php#L546-L596",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "AssetMaintenance"
                ],
                "parameters": [
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled from."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "tag": {},
                                        "name": {},
                                        "category_name": {},
                                        "purchase_cost": {},
                                        "jobs": {
                                            "type": "integer"
                                        },
                                        "completed": {
                                            "type": "integer"
                                        },
                                        "open_jobs": {
                                            "type": "integer"
                                        },
                                        "spend": {},
                                        "spend_ratio": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "jobs": {
                                                    "type": "integer"
                                                },
                                                "open_jobs": {
                                                    "type": "integer"
                                                },
                                                "spend": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/workspace/report/register": {
            "get": {
                "operationId": "get_api_assets_workspace_report_register",
                "tags": [
                    "Asset Workspace"
                ],
                "summary": "Asset register & depreciation report",
                "description": "One row per asset with `method`, `months_depreciated`, `accumulated_depreciation`, `book_value` as of `as_of`, `maintenance_cost`, `total_cost_of_ownership` and disposal info. Paginated with `totals`.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetWorkspaceController@registerReport",
                "x-source": "app/Http/Controllers/AssetWorkspaceController.php#L453-L543",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Asset",
                    "AssetMaintenance"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "as_of",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Valuation date (default today)."
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category."
                    },
                    {
                        "name": "include_disposed",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` to include disposed assets."
                    },
                    {
                        "name": "method",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Depreciation method."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `as_of`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "tag": {},
                                        "name": {},
                                        "category_name": {},
                                        "warehouse_name": {},
                                        "status": {},
                                        "purchase_date": {},
                                        "purchase_cost": {
                                            "type": "number"
                                        },
                                        "method": {},
                                        "useful_life_months": {},
                                        "months_depreciated": {},
                                        "salvage_value": {
                                            "type": "number"
                                        },
                                        "accumulated_depreciation": {},
                                        "book_value": {},
                                        "maintenance_cost": {},
                                        "total_cost_of_ownership": {
                                            "type": "number"
                                        },
                                        "disposal_date": {
                                            "type": "string"
                                        },
                                        "disposal_gain": {},
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "as_of": {
                                            "type": "string"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "purchase_cost": {
                                                    "type": "number"
                                                },
                                                "accumulated_depreciation": {
                                                    "type": "number"
                                                },
                                                "book_value": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets/{asset}": {
            "delete": {
                "operationId": "delete_api_assets_asset",
                "tags": [
                    "Assets"
                ],
                "summary": "Delete an asset",
                "description": "Soft-deletes the asset together with its assignment, maintenance and transfer history visibility.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@destroy",
                "x-source": "app/Http/Controllers/AssetController.php#L205-L212",
                "x-route-name": "assets.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset"
                ],
                "parameters": [
                    {
                        "name": "asset",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Asset id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_assets_asset",
                "tags": [
                    "Assets"
                ],
                "summary": "Get an asset",
                "description": "Full asset record with its category, current assignment, maintenance history, transfers and depreciation figures.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@show",
                "x-source": "app/Http/Controllers/AssetController.php#L100-L125",
                "x-route-name": "assets.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset"
                ],
                "parameters": [
                    {
                        "name": "asset",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Asset id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Asset fields (see tag description).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "tag": {},
                                        "name": {},
                                        "asset_category_id": {},
                                        "serial_number": {},
                                        "description": {},
                                        "purchase_date": {},
                                        "purchase_cost": {},
                                        "supplier": {},
                                        "warranty_expiry": {
                                            "type": "string"
                                        },
                                        "depreciation_method": {},
                                        "useful_life_months": {},
                                        "salvage_value": {},
                                        "status": {},
                                        "warehouse_id": {},
                                        "assigned_to_id": {},
                                        "last_verification": {
                                            "type": "string"
                                        },
                                        "next_validation": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_assets_asset",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Update an asset",
                "description": "Updates an asset with the same fields as creation. Send as multipart when replacing the image.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@update",
                "x-source": "app/Http/Controllers/AssetController.php#L166-L202",
                "x-route-name": "assets.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset"
                ],
                "parameters": [
                    {
                        "name": "asset",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Asset id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "asset_category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "asset_categories,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:asset_categories,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Category."
                                    },
                                    "assigned_to_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Holder."
                                    },
                                    "depreciation_method": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "none",
                                            "straight_line",
                                            "declining_balance"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:none,straight_line,declining_balance"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Method."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "last_verification": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Last check.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "next_validation": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Next check.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "purchase_cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cost."
                                    },
                                    "purchase_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase date."
                                    },
                                    "salvage_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-rules": [
                                            "lte:purchase_cost"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "lte:purchase_cost"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Salvage value."
                                    },
                                    "serial_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Serial."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "supplier": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Supplier."
                                    },
                                    "tag": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'required|unique:assets,tag,' . $id"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'required|unique:assets,tag,' . $id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tag (unique)."
                                    },
                                    "useful_life_months": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 1200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:1200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Useful life."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse."
                                    },
                                    "warranty_expiry": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty end.",
                                        "type": "string",
                                        "format": "date"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_assets_asset",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Update an asset",
                "description": "Updates an asset with the same fields as creation. Send as multipart when replacing the image.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@update",
                "x-source": "app/Http/Controllers/AssetController.php#L166-L202",
                "x-route-name": "assets.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset"
                ],
                "parameters": [
                    {
                        "name": "asset",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Asset id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "asset_category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "asset_categories,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:asset_categories,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Category."
                                    },
                                    "assigned_to_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Holder."
                                    },
                                    "depreciation_method": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "none",
                                            "straight_line",
                                            "declining_balance"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:none,straight_line,declining_balance"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Method."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "last_verification": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Last check.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "next_validation": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Next check.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "purchase_cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cost."
                                    },
                                    "purchase_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase date."
                                    },
                                    "salvage_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-rules": [
                                            "lte:purchase_cost"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "lte:purchase_cost"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Salvage value."
                                    },
                                    "serial_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Serial."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "supplier": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Supplier."
                                    },
                                    "tag": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'required|unique:assets,tag,' . $id"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'required|unique:assets,tag,' . $id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tag (unique)."
                                    },
                                    "useful_life_months": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 1200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:1200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Useful life."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse."
                                    },
                                    "warranty_expiry": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty end.",
                                        "type": "string",
                                        "format": "date"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/assets/{asset}/edit": {
            "get": {
                "operationId": "get_api_assets_asset_edit",
                "tags": [
                    "Assets"
                ],
                "summary": "Edit-form data for an asset",
                "description": "The asset plus the lookup lists needed by the edit form.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@edit",
                "x-source": "app/Http/Controllers/AssetController.php#L258-L307",
                "x-route-name": "assets.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "Asset",
                    "Warehouse",
                    "UserWarehouse",
                    "AssetCategory"
                ],
                "parameters": [
                    {
                        "name": "asset",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Asset id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`asset`, `warehouses[]`, `asset_categories[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "asset": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "tag": {},
                                                "name": {},
                                                "asset_category_id": {},
                                                "serial_number": {},
                                                "description": {},
                                                "purchase_date": {},
                                                "purchase_cost": {},
                                                "supplier": {},
                                                "warranty_expiry": {
                                                    "type": "string"
                                                },
                                                "depreciation_method": {},
                                                "useful_life_months": {},
                                                "salvage_value": {},
                                                "status": {},
                                                "warehouse_id": {},
                                                "assigned_to_id": {},
                                                "last_verification": {
                                                    "type": "string"
                                                },
                                                "next_validation": {
                                                    "type": "string"
                                                }
                                            }
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "asset_categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets_category": {
            "get": {
                "operationId": "get_api_assets_category",
                "tags": [
                    "Asset Categories"
                ],
                "summary": "List asset categories",
                "description": "Paginated when `limit` > 0, otherwise all categories (for selects).",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "CategoryAssetController@index",
                "x-source": "app/Http/Controllers/CategoryAssetController.php#L12-L36",
                "x-route-name": "assets_category.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AssetCategory"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_assets_category",
                "tags": [
                    "Asset Categories"
                ],
                "summary": "Create an asset category",
                "description": "Creates an asset category (name, optional description and default depreciation rate).",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "CategoryAssetController@store",
                "x-source": "app/Http/Controllers/CategoryAssetController.php#L38-L52",
                "x-route-name": "assets_category.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "AssetCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name (max 191)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and `data`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/assets_category/{assets_category}": {
            "delete": {
                "operationId": "delete_api_assets_category_assets_category",
                "tags": [
                    "Asset Categories"
                ],
                "summary": "Delete an asset category",
                "description": "Soft-deletes the category. Assets keep their `category_id`; reassign them first if needed.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "CategoryAssetController@destroy",
                "x-source": "app/Http/Controllers/CategoryAssetController.php#L69-L76",
                "x-route-name": "assets_category.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "AssetCategory"
                ],
                "parameters": [
                    {
                        "name": "assets_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_assets_category_assets_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Asset Categories"
                ],
                "summary": "Update an asset category",
                "description": "Renames a category or changes its description / depreciation defaults.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "CategoryAssetController@update",
                "x-source": "app/Http/Controllers/CategoryAssetController.php#L54-L67",
                "x-route-name": "assets_category.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "AssetCategory"
                ],
                "parameters": [
                    {
                        "name": "assets_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_assets_category_assets_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Asset Categories"
                ],
                "summary": "Update an asset category",
                "description": "Renames a category or changes its description / depreciation defaults.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "CategoryAssetController@update",
                "x-source": "app/Http/Controllers/CategoryAssetController.php#L54-L67",
                "x-route-name": "assets_category.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "assets",
                        "policy": "AssetPolicy"
                    }
                ],
                "x-models": [
                    "AssetCategory"
                ],
                "parameters": [
                    {
                        "name": "assets_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/assets_warehouses": {
            "get": {
                "operationId": "get_api_assets_warehouses",
                "tags": [
                    "Assets"
                ],
                "summary": "Warehouses for asset forms",
                "description": "`{id, name}` of the caller's warehouses.",
                "x-section": "Assets",
                "x-surface": "admin",
                "x-controller": "AssetController@warehouses",
                "x-source": "app/Http/Controllers/AssetController.php#L371-L391",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`data[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/attendances": {
            "get": {
                "operationId": "get_api_attendances",
                "tags": [
                    "Attendances"
                ],
                "summary": "List attendances",
                "description": "Paginated rows mapped to `id, date, clock_in, clock_out, total_work, company_id, employee_id, company_name, employee_username`. `search` matches date, employee username or company name. Restricted to the caller's own records unless they have `record_view`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@index",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L20-L86",
                "x-route-name": "attendances.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Attendance"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`attendances[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "attendances": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_attendances",
                "tags": [
                    "Attendances"
                ],
                "summary": "Record an attendance",
                "description": "Computes lateness / early departure / overtime against the employee's office shift for the weekday of `date`. If the employee clocks in before the shift start, `clock_in` is stored as the shift start; likewise a clock-out exactly at shift end is normalised. `status` is always `present`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@store",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L102-L201",
                "x-route-name": "attendances.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-models": [
                    "Employee",
                    "Attendance"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "clock_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Clock-in time `HH:MM`."
                                    },
                                    "clock_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Clock-out time `HH:MM`."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Attendance date `YYYY-MM-DD`."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee id (must have an office shift)."
                                    }
                                },
                                "required": [
                                    "clock_in",
                                    "clock_out",
                                    "company_id",
                                    "date",
                                    "employee_id"
                                ]
                            },
                            "example": {
                                "company_id": 1,
                                "employee_id": 7,
                                "date": "2026-09-06",
                                "clock_in": "09:12",
                                "clock_out": "18:05"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/attendances/create": {
            "get": {
                "operationId": "get_api_attendances_create",
                "tags": [
                    "Attendances"
                ],
                "summary": "Create-form data for an attendance",
                "description": "Lookup data for the attendance form: companies and employees. No side effects.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@create",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L88-L98",
                "x-route-name": "attendances.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/attendances/delete/by_selection": {
            "post": {
                "operationId": "post_api_attendances_delete_by_selection",
                "tags": [
                    "Attendances"
                ],
                "summary": "Delete selected attendances",
                "description": "Bulk soft-delete of attendance rows by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L339-L352",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-models": [
                    "Attendance"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Attendance ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/attendances/{attendance}": {
            "delete": {
                "operationId": "delete_api_attendances_attendance",
                "tags": [
                    "Attendances"
                ],
                "summary": "Delete an attendance",
                "description": "Soft-deletes an attendance record.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@destroy",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L326-L335",
                "x-route-name": "attendances.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-models": [
                    "Attendance"
                ],
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Attendance id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_attendances_attendance",
                "tags": [
                    "Attendances"
                ],
                "summary": "Get an attendance (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@show",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L205-L209",
                "x-route-name": "attendances.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Attendance id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_attendances_attendance",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Attendances"
                ],
                "summary": "Update an attendance",
                "description": "Same computation as create. **Known quirk:** for a day with no shift configured, the handler returns the computed data without saving.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@update",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L227-L322",
                "x-route-name": "attendances.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-models": [
                    "Employee",
                    "Attendance"
                ],
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Attendance id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "clock_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Clock-in `HH:MM`."
                                    },
                                    "clock_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Clock-out `HH:MM`."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Company id."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee id."
                                    }
                                },
                                "required": [
                                    "clock_in",
                                    "clock_out",
                                    "company_id",
                                    "date",
                                    "employee_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_attendances_attendance",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Attendances"
                ],
                "summary": "Update an attendance",
                "description": "Same computation as create. **Known quirk:** for a day with no shift configured, the handler returns the computed data without saving.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@update",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L227-L322",
                "x-route-name": "attendances.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-models": [
                    "Employee",
                    "Attendance"
                ],
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Attendance id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "clock_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Clock-in `HH:MM`."
                                    },
                                    "clock_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Clock-out `HH:MM`."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Company id."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee id."
                                    }
                                },
                                "required": [
                                    "clock_in",
                                    "clock_out",
                                    "company_id",
                                    "date",
                                    "employee_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/attendances/{attendance}/edit": {
            "get": {
                "operationId": "get_api_attendances_attendance_edit",
                "tags": [
                    "Attendances"
                ],
                "summary": "Edit-form data for an attendance",
                "description": "The attendance record with the lookups needed by the edit form.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\AttendancesController@edit",
                "x-source": "app/Http/Controllers/hrm/AttendancesController.php#L213-L223",
                "x-route-name": "attendances.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "attendance",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "attendance",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Attendance id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/barcode_create_page": {
            "get": {
                "operationId": "get_api_barcode_create_page",
                "tags": [
                    "Products"
                ],
                "summary": "Get barcode-label settings",
                "description": "Data for the *Print barcodes* screen: the caller's `warehouses`, the saved `barcode_label_settings` design, and the direct label-printer configuration from POS settings (`label_printer_enabled`, `label_printer_render_mode` `native`/`raster`, sticker `label_printer_width_mm` / `label_printer_height_mm`, `label_printer_dpi` 203 or 300, X/Y offsets) plus the ASCII `currency_code`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@Get_element_barcode",
                "x-source": "app/Http/Controllers/ProductsController.php#L2672-L2708",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "barcode",
                        "slug": "barcode_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Setting",
                    "PosSetting"
                ],
                "responses": {
                    "200": {
                        "description": "Label settings object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "barcode_label_settings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "label_printer_enabled": {
                                            "type": "boolean"
                                        },
                                        "label_printer_render_mode": {},
                                        "label_printer_width_mm": {},
                                        "label_printer_height_mm": {},
                                        "label_printer_dpi": {
                                            "type": "integer"
                                        },
                                        "label_printer_offset_x_mm": {
                                            "type": "number"
                                        },
                                        "label_printer_offset_y_mm": {
                                            "type": "number"
                                        },
                                        "currency_code": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/barcode_label_settings": {
            "get": {
                "operationId": "get_api_barcode_label_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get barcode label settings",
                "description": "Returns the saved barcode-label template configuration (`template`, `show_name`, `show_price`, `show_barcode`, ...) or `null` when defaults are in use. Requires the `barcode_view` (product barcode) permission.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@getBarcodeLabelSettings",
                "x-source": "app/Http/Controllers/SettingsController.php#L1217-L1224",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "barcode",
                        "slug": "barcode_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{barcode_label_settings: object|null}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "barcode_label_settings": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_barcode_label_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Update barcode label settings",
                "description": "Saves the label template. The payload is whitelisted and coerced: `template` must be one of `template1`…`template5` or `custom` (falls back to `template1`), booleans are cast, numeric sizes are clamped.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@updateBarcodeLabelSettings",
                "x-source": "app/Http/Controllers/SettingsController.php#L1226-L1280",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "barcode",
                        "slug": "barcode_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "settings": {
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Object with `template`, `show_name`, `show_price`, `show_barcode`, `show_company`, `show_category`, `show_batch`, `show_expiry`, size/font fields.",
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "settings"
                                ]
                            },
                            "example": {
                                "settings": {
                                    "template": "template2",
                                    "show_name": true,
                                    "show_price": true,
                                    "show_barcode": true,
                                    "show_company": false
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, barcode_label_settings}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "barcode_label_settings": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/batches_for_adjustment/{product_id}/{warehouse_id}/{variant_id}": {
            "get": {
                "operationId": "get_api_batches_for_adjustment_product_id_warehouse_id_variant_id",
                "tags": [
                    "Stock Adjustments"
                ],
                "summary": "List batches available for an adjustment line",
                "description": "FEFO-ordered active batches of a product (optionally a variant) in a warehouse, for the batch picker on the adjustment form. `supported: false` when batch tracking is not installed.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "AdjustmentController@batches_for_adjustment",
                "x-source": "app/Http/Controllers/AdjustmentController.php#L951-L967",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "adjustment_add",
                        "policy": "AdjustmentPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "product_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Warehouse id."
                    },
                    {
                        "name": "variant_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "x-optional": true,
                        "description": "Variant id; omit or pass `null` for non-variant products."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`supported` and `batches[]` (`id, batch_no, expiry_date, qty, unit_cost`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supported": {},
                                        "batches": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/batches_for_damage/{product_id}/{warehouse_id}/{variant_id}": {
            "get": {
                "operationId": "get_api_batches_for_damage_product_id_warehouse_id_variant_id",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "List batches available for a damage line",
                "description": "FEFO-ordered active batches for the batch picker. `supported: false` when batch tracking is not installed.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@batches_for_damage",
                "x-source": "app/Http/Controllers/DamageController.php#L790-L806",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "damage_view",
                        "policy": "DamagePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "product_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Warehouse id."
                    },
                    {
                        "name": "variant_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "x-optional": true,
                        "description": "Variant id or `null`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`supported` and `batches[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supported": {},
                                        "batches": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/batches_for_quotation/{product_id}/{warehouse_id}/{variant_id}": {
            "get": {
                "operationId": "get_api_batches_for_quotation_product_id_warehouse_id_variant_id",
                "tags": [
                    "Quotations"
                ],
                "summary": "List batches available for a quotation line",
                "description": "FEFO-ordered active batches for the batch picker. `supported: false` when batch tracking is not installed.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@batches_for_quotation",
                "x-source": "app/Http/Controllers/QuotationsController.php#L1438-L1454",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Quotations_add",
                        "policy": "QuotationPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "product_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Warehouse id."
                    },
                    {
                        "name": "variant_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "x-optional": true,
                        "description": "Variant id or `null`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`supported` and `batches[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supported": {},
                                        "batches": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/batches_for_sale/{product_id}/{warehouse_id}/{variant_id}": {
            "get": {
                "operationId": "get_api_batches_for_sale_product_id_warehouse_id_variant_id",
                "tags": [
                    "Sales"
                ],
                "summary": "List batches available for a sale line",
                "description": "FEFO-ordered active batches of a product (optionally a variant) in a warehouse for the batch picker. `supported: false` when batch tracking is not installed.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@batches_for_sale",
                "x-source": "app/Http/Controllers/SalesController.php#L2308-L2324",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "product_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Warehouse id."
                    },
                    {
                        "name": "variant_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "x-optional": true,
                        "description": "Variant id or `null`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`supported` and `batches[]` (`id, batch_no, expiry_date, qty, unit_cost`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supported": {},
                                        "batches": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/batches_for_transfer/{product_id}/{warehouse_id}/{variant_id}": {
            "get": {
                "operationId": "get_api_batches_for_transfer_product_id_warehouse_id_variant_id",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "List batches available for a transfer line",
                "description": "FEFO-ordered active batches in the **source** warehouse for the batch picker. `supported: false` when batch tracking is not installed.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@batches_for_transfer",
                "x-source": "app/Http/Controllers/TransferController.php#L981-L997",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "transfer_add",
                        "policy": "TransferPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "product_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Source warehouse id."
                    },
                    {
                        "name": "variant_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "x-optional": true,
                        "description": "Variant id or `null`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`supported` and `batches[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supported": {},
                                        "batches": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/booking_pdf/{id}": {
            "get": {
                "operationId": "get_api_booking_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Booking confirmation PDF",
                "description": "Customer, product, price, booking date and status. Requires the `view` permission on bookings.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "BookingController@booking_pdf",
                "x-source": "app/Http/Controllers/BookingController.php#L473-L516",
                "x-middleware": [
                    "api"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-models": [
                    "Booking",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Booking ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/bookings": {
            "get": {
                "operationId": "get_api_bookings",
                "tags": [
                    "Bookings"
                ],
                "summary": "List bookings",
                "description": "Paginated bookings with `customer_name` and `service_name`. `search` matches customer, service and notes. Sortable by `id`, `booking_date`, `booking_time`, `status`. `stats` counts bookings per status for the filtered set.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@index",
                "x-source": "app/Http/Controllers/BookingController.php#L32-L162",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Booking"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Exact booking date."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Range start (calendar views)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `confirmed`, `cancelled` or `completed`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Range end."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`bookings[]`, `totalRows`, `stats`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "bookings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_bookings",
                "tags": [
                    "Bookings"
                ],
                "summary": "Create a booking",
                "description": "Creates a booking with an auto-generated `Ref`. Times accept `HH:MM` or `HH:MM:SS` (seconds are dropped). Returns HTTP **201**.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@store",
                "x-source": "app/Http/Controllers/BookingController.php#L221-L278",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Booking"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Total amount."
                                    },
                                    "booking_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Date (`YYYY-MM-DD`). Required."
                                    },
                                    "booking_end_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "End time `HH:MM`."
                                    },
                                    "booking_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "x-laravel-rules": [
                                            "required",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Start time `HH:MM`. Required."
                                    },
                                    "customer_id": {
                                        "type": "integer",
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "delivery_address": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Delivery address."
                                    },
                                    "delivery_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Delivery date."
                                    },
                                    "delivery_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Delivery time `HH:MM`."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unit price."
                                    },
                                    "product_description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Free-text description."
                                    },
                                    "product_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "products,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Service product id."
                                    },
                                    "product_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Free-text product/service name (when not using a product)."
                                    },
                                    "sales_person_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "users,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:users,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "User id of the salesperson."
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "confirmed",
                                            "cancelled",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "in:pending,confirmed,cancelled,completed"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`pending`, `confirmed`, `cancelled`, `completed`. Required."
                                    },
                                    "tray_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "trays,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:trays,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Tray / table id."
                                    }
                                },
                                "required": [
                                    "booking_date",
                                    "booking_time",
                                    "customer_id",
                                    "status"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            },
                            "example": {
                                "customer_id": 3,
                                "product_id": 22,
                                "booking_date": "2026-09-10",
                                "booking_time": "14:00",
                                "booking_end_time": "15:00",
                                "price": 50,
                                "amount": 50,
                                "status": "confirmed",
                                "notes": "Bring the old unit"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and new `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/bookings/create": {
            "get": {
                "operationId": "get_api_bookings_create",
                "tags": [
                    "Bookings"
                ],
                "summary": "Get lookups for the booking form",
                "description": "`customers`, service `products` (`id, name, code, price`), `trays`, `sales_persons` and the `statuses` list.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@create",
                "x-source": "app/Http/Controllers/BookingController.php#L167-L186",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Product"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "trays": {},
                                        "sales_persons": {},
                                        "statuses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/bookings/{id}": {
            "delete": {
                "operationId": "delete_api_bookings_id",
                "tags": [
                    "Bookings"
                ],
                "summary": "Delete a booking",
                "description": "Soft-deletes the booking; already deleted bookings answer `success: true` with a message.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@destroy",
                "x-source": "app/Http/Controllers/BookingController.php#L437-L450",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-models": [
                    "Booking"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Booking id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Booking already deleted"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_bookings_id",
                "tags": [
                    "Bookings"
                ],
                "summary": "Get a booking",
                "description": "Full booking with resolved names (`customer_name`, `service_name`, `tray_name`, `sales_person_name`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@show",
                "x-source": "app/Http/Controllers/BookingController.php#L283-L325",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-models": [
                    "Booking"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Booking id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`booking` object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "booking": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "Ref": {},
                                                "customer_id": {},
                                                "customer_name": {},
                                                "product_id": {},
                                                "service_name": {},
                                                "product_name": {},
                                                "product_description": {},
                                                "tray_id": {},
                                                "tray_name": {},
                                                "sales_person_id": {},
                                                "sales_person_name": {
                                                    "type": "string"
                                                },
                                                "price": {},
                                                "amount": {},
                                                "booking_date": {},
                                                "booking_time": {},
                                                "booking_end_time": {},
                                                "delivery_date": {},
                                                "delivery_time": {},
                                                "delivery_address": {},
                                                "status": {},
                                                "notes": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_bookings_id",
                "tags": [
                    "Bookings"
                ],
                "summary": "Update a booking",
                "description": "Replaces all booking fields (same validation as create).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@update",
                "x-source": "app/Http/Controllers/BookingController.php#L376-L432",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Booking"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Booking id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Amount."
                                    },
                                    "booking_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Date. Required."
                                    },
                                    "booking_end_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "End `HH:MM`."
                                    },
                                    "booking_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "x-laravel-rules": [
                                            "required",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Start `HH:MM`. Required."
                                    },
                                    "customer_id": {
                                        "type": "integer",
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "delivery_address": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Address."
                                    },
                                    "delivery_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Delivery date."
                                    },
                                    "delivery_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Delivery time."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Price."
                                    },
                                    "product_description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "product_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "products,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Service product id."
                                    },
                                    "product_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Free-text name."
                                    },
                                    "sales_person_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "users,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:users,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Salesperson user id."
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "confirmed",
                                            "cancelled",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "in:pending,confirmed,cancelled,completed"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Status. Required."
                                    },
                                    "tray_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "trays,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:trays,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Tray id."
                                    }
                                },
                                "required": [
                                    "booking_date",
                                    "booking_time",
                                    "customer_id",
                                    "status"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/bookings/{id}/edit": {
            "get": {
                "operationId": "get_api_bookings_id_edit",
                "tags": [
                    "Bookings"
                ],
                "summary": "Get a booking for editing",
                "description": "The raw booking fields plus the same lookups as the create form.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@edit",
                "x-source": "app/Http/Controllers/BookingController.php#L330-L371",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-models": [
                    "Booking",
                    "Client",
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Booking id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`booking`, `customers`, `products`, `trays`, `sales_persons`, `statuses`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "booking": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "Ref": {},
                                                "customer_id": {},
                                                "product_id": {},
                                                "tray_id": {},
                                                "sales_person_id": {},
                                                "product_name": {},
                                                "product_description": {},
                                                "price": {},
                                                "amount": {},
                                                "booking_date": {},
                                                "booking_time": {},
                                                "booking_end_time": {},
                                                "delivery_date": {},
                                                "delivery_time": {},
                                                "delivery_address": {},
                                                "status": {},
                                                "notes": {}
                                            }
                                        },
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "trays": {},
                                        "sales_persons": {},
                                        "statuses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/bookings/{id}/status": {
            "put": {
                "operationId": "put_api_bookings_id_status",
                "tags": [
                    "Bookings"
                ],
                "summary": "Change a booking's status",
                "description": "Sets only `status`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@changeStatus",
                "x-source": "app/Http/Controllers/BookingController.php#L455-L468",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-models": [
                    "Booking"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Booking id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "confirmed",
                                            "cancelled",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "in:pending,confirmed,cancelled,completed"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`pending`, `confirmed`, `cancelled`, `completed`."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/bookings_send_email": {
            "post": {
                "operationId": "post_api_bookings_send_email",
                "tags": [
                    "Bookings"
                ],
                "summary": "Email a booking confirmation",
                "description": "Sends the *booking* email template to the customer with `{contact_name}`, `{business_name}`, `{booking_number}`, `{booking_date}`, `{start_time}`, `{end_time}`, `{service_name}`, `{booking_url}` (public PDF).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "BookingController@Send_Email",
                "x-source": "app/Http/Controllers/BookingController.php#L540-L608",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "BookingPolicy"
                    }
                ],
                "x-models": [
                    "Booking",
                    "Setting",
                    "EmailMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Booking id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully.\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Missing id, customer or customer email.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Customer has no email address."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/brands": {
            "get": {
                "operationId": "get_api_brands",
                "tags": [
                    "Brands"
                ],
                "summary": "List brands",
                "description": "Paginated brands. `search` matches name or description.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "BrandsController@index",
                "x-source": "app/Http/Controllers/BrandsController.php#L15-L50",
                "x-route-name": "brands.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "brand",
                        "policy": "BrandPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Brand"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`brands[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "brands": [
                                        {
                                            "id": 1,
                                            "name": "Acme",
                                            "description": "House brand",
                                            "image": "no-image.png"
                                        }
                                    ],
                                    "totalRows": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_brands",
                "tags": [
                    "Brands"
                ],
                "summary": "Create a brand",
                "description": "Creates a brand. When an `image` is uploaded it is resized to 200×200; otherwise `no-image.png` is used. Returns HTTP **201**.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "BrandsController@store",
                "x-source": "app/Http/Controllers/BrandsController.php#L54-L93",
                "x-route-name": "brands.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "brand",
                        "policy": "BrandPolicy"
                    }
                ],
                "x-models": [
                    "Brand"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Optional description."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 2048,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Optional logo image, max 2 MB."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Brand name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "brand": {
                                        "id": 3,
                                        "name": "Acme",
                                        "description": "House brand",
                                        "image": "45678912logo.png"
                                    }
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and the created `brand`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "brand": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/brands/delete/by_selection": {
            "post": {
                "operationId": "post_api_brands_delete_by_selection",
                "tags": [
                    "Brands"
                ],
                "summary": "Delete several brands",
                "description": "Soft-deletes each id in `selectedIds`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "BrandsController@delete_by_selection",
                "x-source": "app/Http/Controllers/BrandsController.php#L171-L185",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "brand",
                        "policy": "BrandPolicy"
                    }
                ],
                "x-models": [
                    "Brand"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of brand ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/brands/{brand}": {
            "delete": {
                "operationId": "delete_api_brands_brand",
                "tags": [
                    "Brands"
                ],
                "summary": "Delete a brand",
                "description": "Soft-deletes the brand; products keep their `brand_id`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "BrandsController@destroy",
                "x-source": "app/Http/Controllers/BrandsController.php#L158-L167",
                "x-route-name": "brands.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "brand",
                        "policy": "BrandPolicy"
                    }
                ],
                "x-models": [
                    "Brand"
                ],
                "parameters": [
                    {
                        "name": "brand",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Brand id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_brands_brand",
                "tags": [
                    "Brands"
                ],
                "summary": "(Not implemented) Get a brand",
                "description": "Resource stub with an empty body; returns an empty `200`. Use the list endpoint.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "BrandsController@show",
                "x-source": "app/Http/Controllers/BrandsController.php#L97-L101",
                "x-route-name": "brands.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "brand",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Brand id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_brands_brand",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Brands"
                ],
                "summary": "Update a brand",
                "description": "Updates name, description and optionally the logo. Send `image` as a file to replace the logo (the previous file is deleted), or omit it / send the string `null` to keep the current one.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "BrandsController@update",
                "x-source": "app/Http/Controllers/BrandsController.php#L105-L154",
                "x-route-name": "brands.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "brand",
                        "policy": "BrandPolicy"
                    }
                ],
                "x-models": [
                    "Brand"
                ],
                "parameters": [
                    {
                        "name": "brand",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Brand id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 2048,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read",
                                            "file"
                                        ],
                                        "description": "New logo file (max 2 MB) or omit to keep."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Brand name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_brands_brand",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Brands"
                ],
                "summary": "Update a brand",
                "description": "Updates name, description and optionally the logo. Send `image` as a file to replace the logo (the previous file is deleted), or omit it / send the string `null` to keep the current one.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "BrandsController@update",
                "x-source": "app/Http/Controllers/BrandsController.php#L105-L154",
                "x-route-name": "brands.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "brand",
                        "policy": "BrandPolicy"
                    }
                ],
                "x-models": [
                    "Brand"
                ],
                "parameters": [
                    {
                        "name": "brand",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Brand id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 2048,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read",
                                            "file"
                                        ],
                                        "description": "New logo file (max 2 MB) or omit to keep."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Brand name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/cash-registers/cash-move": {
            "post": {
                "operationId": "post_api_cash_registers_cash_move",
                "tags": [
                    "Cash Registers"
                ],
                "summary": "Record cash in or out",
                "description": "Adds `amount` to the register's `cash_in` or `cash_out` counter and appends a timestamped line to its notes. The register must be open (`409` otherwise).",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "CashRegisterController@cashInOut",
                "x-source": "app/Http/Controllers/CashRegisterController.php#L66-L93",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "CashRegister"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Amount (≥ 0)."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reason."
                                    },
                                    "register_id": {
                                        "type": "integer",
                                        "x-exists": "cash_registers,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:cash_registers,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Open register id."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "in",
                                            "out"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:in,out"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`in` or `out`."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "register_id",
                                    "type"
                                ]
                            },
                            "example": {
                                "register_id": 7,
                                "type": "out",
                                "amount": 20,
                                "notes": "Bought receipt paper"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and updated `register`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "register": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "409": {
                        "description": "Register is closed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Register is closed"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/cash-registers/close": {
            "post": {
                "operationId": "post_api_cash_registers_close",
                "tags": [
                    "Cash Registers"
                ],
                "summary": "Close a cash register",
                "description": "Closes the session: sums the cashier's POS sales in the warehouse since opening into `total_sales`, computes `expected_cash` and the `difference` against `counted_cash`, stores `closing_balance` (defaults to the counted cash) and marks the register `closed`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "CashRegisterController@closeRegister",
                "x-source": "app/Http/Controllers/CashRegisterController.php#L95-L147",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "CashRegister",
                    "Sale"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "closing_balance": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Closing balance to record (defaults to `counted_cash`)."
                                    },
                                    "counted_cash": {
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Cash physically counted."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Closing notes."
                                    },
                                    "register_id": {
                                        "type": "integer",
                                        "x-exists": "cash_registers,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:cash_registers,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Open register id."
                                    }
                                },
                                "required": [
                                    "counted_cash",
                                    "register_id"
                                ]
                            },
                            "example": {
                                "register_id": 7,
                                "counted_cash": 640.5,
                                "notes": "All good"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `register`, `summary {expected_cash, counted_cash, difference}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "register": {},
                                        "summary": {
                                            "type": "object",
                                            "properties": {
                                                "expected_cash": {},
                                                "counted_cash": {},
                                                "difference": {}
                                            }
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "register": {
                                        "id": 7,
                                        "status": "closed",
                                        "total_sales": 560.5,
                                        "difference": 0
                                    },
                                    "summary": {
                                        "expected_cash": 640.5,
                                        "counted_cash": 640.5,
                                        "difference": 0
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "409": {
                        "description": "Register already closed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Register already closed"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/cash-registers/current/{user_id}": {
            "get": {
                "operationId": "get_api_cash_registers_current_user_id",
                "tags": [
                    "Cash Registers"
                ],
                "summary": "Get a user's open register",
                "description": "The latest **open** register of `user_id`, optionally limited to `warehouse_id`, with its user and warehouse. `register` is `null` when none is open.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "CashRegisterController@getCurrentRegister",
                "x-source": "app/Http/Controllers/CashRegisterController.php#L49-L64",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "CashRegister"
                ],
                "parameters": [
                    {
                        "name": "user_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Cashier user id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Restrict to this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `register` (or `null`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "register": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/cash-registers/open": {
            "post": {
                "operationId": "post_api_cash_registers_open",
                "tags": [
                    "Cash Registers"
                ],
                "summary": "Open a cash register",
                "description": "Opens a register session for the caller in `warehouse_id` with an `opening_balance`. Only one open register per user and warehouse (`409` otherwise).",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "CashRegisterController@openRegister",
                "x-source": "app/Http/Controllers/CashRegisterController.php#L17-L47",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "CashRegister"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "opening_balance": {
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Cash float at opening."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                },
                                "required": [
                                    "opening_balance",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "warehouse_id": 1,
                                "opening_balance": 100,
                                "notes": "Morning shift"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the `register` row.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "register": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Register already open.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Register already open"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/categories": {
            "get": {
                "operationId": "get_api_categories",
                "tags": [
                    "Categories"
                ],
                "summary": "List categories",
                "description": "Paginated categories. `search` matches `name` or `code`. `SortField` is whitelisted to `id`, `name`, `code`, `created_at`, `updated_at` (anything else falls back to `id`).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "CategorieController@index",
                "x-source": "app/Http/Controllers/CategorieController.php#L15-L63",
                "x-route-name": "categories.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "category",
                        "policy": "CategoryPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Category"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`categories[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "categories": [
                                        {
                                            "id": 2,
                                            "code": "APP",
                                            "name": "Apparel",
                                            "icon": "shirt",
                                            "created_at": "2026-01-10T09:00:00.000000Z"
                                        }
                                    ],
                                    "totalRows": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_categories",
                "tags": [
                    "Categories"
                ],
                "summary": "Create a category",
                "description": "Creates a category. Returns HTTP **201** with the created row.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "CategorieController@store",
                "x-source": "app/Http/Controllers/CategorieController.php#L68-L88",
                "x-route-name": "categories.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "category",
                        "policy": "CategoryPolicy"
                    }
                ],
                "x-models": [
                    "Category"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Short code, max 190."
                                    },
                                    "icon": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Optional icon name (max 64) for the storefront menu."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category name, max 190."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Apparel",
                                "code": "APP",
                                "icon": "shirt"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and the created `category`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "category": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/categories/delete/by_selection": {
            "post": {
                "operationId": "post_api_categories_delete_by_selection",
                "tags": [
                    "Categories"
                ],
                "summary": "Delete several categories",
                "description": "Soft-deletes every id in `selectedIds`. An empty list is a no-op.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "CategorieController@delete_by_selection",
                "x-source": "app/Http/Controllers/CategorieController.php#L140-L154",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "category",
                        "policy": "CategoryPolicy"
                    }
                ],
                "x-models": [
                    "Category"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of category ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            },
                            "example": {
                                "selectedIds": [
                                    4,
                                    5
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/categories/{category}": {
            "delete": {
                "operationId": "delete_api_categories_category",
                "tags": [
                    "Categories"
                ],
                "summary": "Delete a category",
                "description": "Soft-deletes the category. Products keep their `category_id`; the product edit form then shows an empty category.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "CategorieController@destroy",
                "x-source": "app/Http/Controllers/CategorieController.php#L125-L134",
                "x-route-name": "categories.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "category",
                        "policy": "CategoryPolicy"
                    }
                ],
                "x-models": [
                    "Category"
                ],
                "parameters": [
                    {
                        "name": "category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_categories_category",
                "tags": [
                    "Categories"
                ],
                "summary": "Get a category",
                "description": "Returns one category row. Deleted categories return 404. No permission check beyond authentication.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "CategorieController@show",
                "x-source": "app/Http/Controllers/CategorieController.php#L93-L98",
                "x-route-name": "categories.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Category"
                ],
                "parameters": [
                    {
                        "name": "category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Category object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_categories_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Categories"
                ],
                "summary": "Update a category",
                "description": "Replaces `name`, `code` and `icon`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "CategorieController@update",
                "x-source": "app/Http/Controllers/CategorieController.php#L103-L120",
                "x-route-name": "categories.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "category",
                        "policy": "CategoryPolicy"
                    }
                ],
                "x-models": [
                    "Category"
                ],
                "parameters": [
                    {
                        "name": "category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Short code, max 190."
                                    },
                                    "icon": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Icon name or `null`."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category name, max 190."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Apparel & Shoes",
                                "code": "APP",
                                "icon": "shirt"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_categories_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Categories"
                ],
                "summary": "Update a category",
                "description": "Replaces `name`, `code` and `icon`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "CategorieController@update",
                "x-source": "app/Http/Controllers/CategorieController.php#L103-L120",
                "x-route-name": "categories.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "category",
                        "policy": "CategoryPolicy"
                    }
                ],
                "x-models": [
                    "Category"
                ],
                "parameters": [
                    {
                        "name": "category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Short code, max 190."
                                    },
                                    "icon": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Icon name or `null`."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category name, max 190."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Apparel & Shoes",
                                "code": "APP",
                                "icon": "shirt"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/check_phone_duplicate": {
            "get": {
                "operationId": "get_api_check_phone_duplicate",
                "tags": [
                    "Users"
                ],
                "summary": "Check whether a phone number is already used",
                "description": "Form helper: returns `exists: true` when another record of the given `type` already has this phone number. `exclude_id` ignores the record being edited. Empty phone or unknown type returns `exists: false`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@checkPhoneDuplicate",
                "x-source": "app/Http/Controllers/UserController.php#L532-L560",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Client",
                    "Provider",
                    "User"
                ],
                "parameters": [
                    {
                        "name": "exclude_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Id of the record being edited, excluded from the check."
                    },
                    {
                        "name": "phone",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Phone number to check."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`user`, `client` or `provider`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"exists\": boolean }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "exists": {
                                            "type": "boolean"
                                        }
                                    }
                                },
                                "example": {
                                    "exists": false
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clear_cache": {
            "get": {
                "operationId": "get_api_clear_cache",
                "tags": [
                    "System Settings"
                ],
                "summary": "Clear application caches",
                "description": "Runs `cache:clear`, `view:clear` and `route:clear`. Returns an empty 200 body. Use after changing translations or settings that are cached server-side.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@Clear_Cache",
                "x-source": "app/Http/Controllers/SettingsController.php#L1796-L1801",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/client_ledger_pdf": {
            "get": {
                "operationId": "get_api_client_ledger_pdf",
                "tags": [
                    "Customers"
                ],
                "summary": "Download a customer ledger PDF",
                "description": "Generates a PDF statement for one customer: contact block, balance summary (`salesGrand`, `salesPaid`, `sale_due`, `return_due`, `paymentsTotal`, `quotationsTotal`, `netBalance`) followed by the lists of sales, payments, quotations and returns. Rendered with the company details from System Settings.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@export",
                "x-source": "app/Http/Controllers/ClientController.php#L1166-L1296",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Sale",
                    "Quotation",
                    "SaleReturn",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "x-exists": "clients,id",
                            "x-laravel-rules": [
                                "required",
                                "integer",
                                "exists:clients,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Customer id (query string, required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file (`application/pdf`).",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients": {
            "get": {
                "operationId": "get_api_clients",
                "tags": [
                    "Customers"
                ],
                "summary": "List customers",
                "description": "Paginated list of customers with their financial position. For every customer the response adds:\n\n- `total_amount` – sum of `GrandTotal` of **completed** sales\n- `total_paid` – sum of `paid_amount` of completed sales\n- `due` – `total_amount - total_paid`\n- `total_amount_return` / `total_paid_return` / `return_Due` – the same for sale returns (what you owe the customer)\n- `client_ecommerce` – `\"yes\"` when the customer has an online-store account\n\nAlongside the list it returns lookups the UI needs: `company_info`, `accounts` (treasury accounts for the pay-due dialog) and `payment_methods`. Soft-deleted customers are excluded.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@index",
                "x-source": "app/Http/Controllers/ClientController.php#L31-L159",
                "x-route-name": "clients.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "name",
                    "code",
                    "phone",
                    "email"
                ],
                "x-models": [
                    "Client",
                    "EcommerceClient",
                    "Setting",
                    "Account",
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on the customer code (auto-generated sequential number)."
                    },
                    {
                        "name": "email",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on the email address."
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on the customer name (SQL `LIKE`, so `%` wildcards work)."
                    },
                    {
                        "name": "phone",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on the phone number."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Page of customers plus `totalRows`, `company_info`, `accounts` and `payment_methods`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "company_info": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "clients_without_ecommerce": {},
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "clients": [
                                        {
                                            "id": 3,
                                            "code": 3,
                                            "name": "ACME Ltd",
                                            "firstname": "Jane",
                                            "lastname": "Doe",
                                            "phone": "+212600000000",
                                            "email": "billing@acme.test",
                                            "adresse": "12 Main St",
                                            "country": "MA",
                                            "city": "Casablanca",
                                            "state": null,
                                            "zip": "20000",
                                            "tax_number": "TX-123",
                                            "opening_balance": 0,
                                            "credit_limit": 5000,
                                            "points": 120,
                                            "is_royalty_eligible": 1,
                                            "total_amount": 1540.5,
                                            "total_paid": 1000,
                                            "due": 540.5,
                                            "total_amount_return": 0,
                                            "total_paid_return": 0,
                                            "return_Due": 0,
                                            "client_ecommerce": "yes"
                                        }
                                    ],
                                    "totalRows": 1,
                                    "company_info": {
                                        "CompanyName": "Stocky",
                                        "CompanyPhone": "…"
                                    },
                                    "accounts": [
                                        {
                                            "id": 1,
                                            "account_name": "Main cash"
                                        }
                                    ],
                                    "payment_methods": [
                                        {
                                            "id": 1,
                                            "name": "Cash"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_clients",
                "tags": [
                    "Customers"
                ],
                "summary": "Create a customer",
                "description": "Creates a customer. The `code` is generated automatically (next sequential number). `email`, when given, must be unique across both customers and online-store accounts. `opening_balance` and `credit_limit` default to `0`.\n\nThe new customer row is returned as the response body.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@store",
                "x-source": "app/Http/Controllers/ClientController.php#L163-L205",
                "x-route-name": "clients.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Customers_add",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "adresse": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Street address (field name is French spelling)."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "credit_limit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Maximum outstanding due allowed for this customer; POS/sales warn when exceeded. Default `0` = no limit."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-unique": "ecommerce_clients,email ->whereNull",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:255",
                                            "unique:clients,email ->whereNull",
                                            "unique:ecommerce_clients,email ->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email address. Must be unique among non-deleted customers and store accounts."
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First name (optional, for individuals)."
                                    },
                                    "is_royalty_eligible": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1`/`true` to let the customer earn and redeem loyalty points."
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last name (optional)."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Display name of the customer (company or full name). Required."
                                    },
                                    "opening_balance": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount the customer already owed before using Stocky. Paid down first by the pay-due endpoint. Default `0`."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number."
                                    },
                                    "state": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "State / region."
                                    },
                                    "tax_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "VAT / tax identification number printed on invoices."
                                    },
                                    "zip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "ACME Ltd",
                                "firstname": "Jane",
                                "lastname": "Doe",
                                "email": "billing@acme.test",
                                "phone": "+212600000000",
                                "adresse": "12 Main St",
                                "country": "MA",
                                "city": "Casablanca",
                                "zip": "20000",
                                "tax_number": "TX-123",
                                "opening_balance": 0,
                                "credit_limit": 5000,
                                "is_royalty_eligible": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The created customer row.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": 12,
                                    "code": 12,
                                    "name": "ACME Ltd",
                                    "email": "billing@acme.test",
                                    "opening_balance": 0,
                                    "credit_limit": 5000,
                                    "is_royalty_eligible": 1,
                                    "created_at": "2026-09-06T10:00:00.000000Z",
                                    "updated_at": "2026-09-06T10:00:00.000000Z"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients/delete/by_selection": {
            "post": {
                "operationId": "post_api_clients_delete_by_selection",
                "tags": [
                    "Customers"
                ],
                "summary": "Delete several customers",
                "description": "Soft-deletes every customer in `selectedIds`, together with their linked store accounts, in one transaction.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@delete_by_selection",
                "x-source": "app/Http/Controllers/ClientController.php#L347-L373",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Customers_delete",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "EcommerceClient"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer",
                                            "x-laravel-rules": [
                                                "integer"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Array of customer ids (at least one, integers)."
                                    }
                                },
                                "required": [
                                    "selectedIds"
                                ]
                            },
                            "example": {
                                "selectedIds": [
                                    4,
                                    7,
                                    9
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients/{client}": {
            "delete": {
                "operationId": "delete_api_clients_client",
                "tags": [
                    "Customers"
                ],
                "summary": "Delete a customer",
                "description": "Soft-deletes the customer (sets `deleted_at`) and soft-deletes + deactivates any linked online-store account. Sales and other documents that reference the customer are kept.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@destroy",
                "x-source": "app/Http/Controllers/ClientController.php#L323-L343",
                "x-route-name": "clients.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Customers_delete",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "EcommerceClient"
                ],
                "parameters": [
                    {
                        "name": "client",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_clients_client",
                "tags": [
                    "Customers"
                ],
                "summary": "Get a customer",
                "description": "Returns one customer record together with the treasury `accounts` and active `payment_methods` lists needed by the payment dialogs. Soft-deleted customers return 404. No permission check beyond authentication.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@show",
                "x-source": "app/Http/Controllers/ClientController.php#L209-L221",
                "x-route-name": "clients.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Client",
                    "Account",
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "client",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`client` object plus `accounts` and `payment_methods` lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "client": {},
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "client": {
                                        "id": 3,
                                        "code": 3,
                                        "name": "ACME Ltd",
                                        "email": "billing@acme.test",
                                        "phone": "+212600000000",
                                        "opening_balance": 0,
                                        "credit_limit": 5000,
                                        "points": 120
                                    },
                                    "accounts": [
                                        {
                                            "id": 1,
                                            "account_name": "Main cash"
                                        }
                                    ],
                                    "payment_methods": [
                                        {
                                            "id": 1,
                                            "name": "Cash"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_clients_client",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Customers"
                ],
                "summary": "Update a customer",
                "description": "Updates a customer and, optionally, the linked online-store account in the same transaction.\n\n- Customer fields are all replaced with the submitted values (send the full record).\n- `opening_balance` is **not** editable here — use *Adjust opening balance*.\n- `username`, `password` and `status` apply to the linked store account (`ecommerce_clients`) when one exists; `email` is kept in sync between the two records.\n- `email` must stay unique across customers and store accounts (the customer's own rows are ignored).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@update",
                "x-source": "app/Http/Controllers/ClientController.php#L225-L319",
                "x-route-name": "clients.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient",
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "client",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "adresse": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Street address."
                                    },
                                    "city": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "credit_limit": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Credit limit, `>= 0`."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-unique": "ecommerce_clients,email ->ignore->whereNull",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:255",
                                            "unique:clients,email ->ignore->whereNull",
                                            "unique:ecommerce_clients,email ->ignore->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email; unique across customers and store accounts."
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "is_royalty_eligible": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Loyalty flag; accepts `1`, `0`, `true`, `false`."
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Display name. Required."
                                    },
                                    "password": {
                                        "type": "string",
                                        "minLength": 6,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "min:6"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New store-account password (min 6 chars). Omit to keep the current one."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone number (max 50 chars)."
                                    },
                                    "state": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "State / region."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "inactive"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:active,inactive"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Store-account status: `active` or `inactive`."
                                    },
                                    "tax_number": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tax identification number."
                                    },
                                    "username": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-unique": "ecommerce_clients,username ->ignore",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100",
                                            "unique:ecommerce_clients,username ->ignore"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Store-account username (only if the customer has a store account)."
                                    },
                                    "zip": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "ACME Ltd",
                                "email": "billing@acme.test",
                                "phone": "+212600000000",
                                "adresse": "12 Main St",
                                "city": "Casablanca",
                                "country": "MA",
                                "zip": "20000",
                                "credit_limit": 8000,
                                "is_royalty_eligible": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_clients_client",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Customers"
                ],
                "summary": "Update a customer",
                "description": "Updates a customer and, optionally, the linked online-store account in the same transaction.\n\n- Customer fields are all replaced with the submitted values (send the full record).\n- `opening_balance` is **not** editable here — use *Adjust opening balance*.\n- `username`, `password` and `status` apply to the linked store account (`ecommerce_clients`) when one exists; `email` is kept in sync between the two records.\n- `email` must stay unique across customers and store accounts (the customer's own rows are ignored).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@update",
                "x-source": "app/Http/Controllers/ClientController.php#L225-L319",
                "x-route-name": "clients.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient",
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "client",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "adresse": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Street address."
                                    },
                                    "city": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "credit_limit": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Credit limit, `>= 0`."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-unique": "ecommerce_clients,email ->ignore->whereNull",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:255",
                                            "unique:clients,email ->ignore->whereNull",
                                            "unique:ecommerce_clients,email ->ignore->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email; unique across customers and store accounts."
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "is_royalty_eligible": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Loyalty flag; accepts `1`, `0`, `true`, `false`."
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Display name. Required."
                                    },
                                    "password": {
                                        "type": "string",
                                        "minLength": 6,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "min:6"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New store-account password (min 6 chars). Omit to keep the current one."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone number (max 50 chars)."
                                    },
                                    "state": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "State / region."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "inactive"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:active,inactive"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Store-account status: `active` or `inactive`."
                                    },
                                    "tax_number": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tax identification number."
                                    },
                                    "username": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-unique": "ecommerce_clients,username ->ignore",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100",
                                            "unique:ecommerce_clients,username ->ignore"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Store-account username (only if the customer has a store account)."
                                    },
                                    "zip": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "ACME Ltd",
                                "email": "billing@acme.test",
                                "phone": "+212600000000",
                                "adresse": "12 Main St",
                                "city": "Casablanca",
                                "country": "MA",
                                "zip": "20000",
                                "credit_limit": 8000,
                                "is_royalty_eligible": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/clients/{id}/brief": {
            "get": {
                "operationId": "get_api_clients_id_brief",
                "tags": [
                    "Customers"
                ],
                "summary": "Get customer header with balances",
                "description": "Compact customer record for the ledger/detail page header. Returns the core fields plus computed balances:\n\n- `salesGrand`, `salesPaid`, `sale_due` – completed sales totals and what is still owed\n- `return_due` – sale-return amount not yet refunded to the customer\n- `paymentsTotal` – sum of all sale payments received\n- `netBalance` – `opening_balance + sale_due - return_due` (positive = customer owes you)\n- `wallet_enabled`, `wallet_balance` – store-wallet balance when the wallet module is on",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@clientBrief",
                "x-source": "app/Http/Controllers/ClientController.php#L1104-L1164",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Customer with computed balance fields.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": 3,
                                    "name": "ACME Ltd",
                                    "email": "billing@acme.test",
                                    "phone": "+212600000000",
                                    "code": 3,
                                    "opening_balance": 200,
                                    "credit_limit": 5000,
                                    "points": 120,
                                    "salesGrand": 1540.5,
                                    "salesPaid": 1000,
                                    "sale_due": 540.5,
                                    "return_due": 0,
                                    "paymentsTotal": 1000,
                                    "netBalance": 740.5,
                                    "wallet_enabled": false,
                                    "wallet_balance": 0
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients/{id}/portal-disable": {
            "post": {
                "operationId": "post_api_clients_id_portal_disable",
                "tags": [
                    "Customers"
                ],
                "summary": "Disable client-portal access",
                "description": "Sets the portal account status to `0` so the client can no longer log in. The record and password are kept, so *portal-enable* restores access.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "Api\\Portal\\PortalAdminController@disable",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAdminController.php#L83-L95",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "PortalClient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Confirmation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Portal access disabled"
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "message": "Portal access disabled"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients/{id}/portal-enable": {
            "post": {
                "operationId": "post_api_clients_id_portal_enable",
                "tags": [
                    "Customers"
                ],
                "summary": "Enable client-portal access",
                "description": "Creates or re-activates the customer's portal login (`portal_clients`). Any pending invitation token is cleared. If `password` is provided it becomes the login password; otherwise a random 32-character password is set when the account has none yet (share credentials with the client, or let them use the invite flow).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "Api\\Portal\\PortalAdminController@enable",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAdminController.php#L37-L78",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "PortalClient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:$emailRules"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:$emailRules"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Portal login email (max 190 chars). Must be unique among portal accounts."
                                    },
                                    "password": {
                                        "type": "string",
                                        "minLength": 8,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "min:8"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Optional password, min 8 chars."
                                    }
                                }
                            },
                            "example": {
                                "email": "jane@acme.test",
                                "password": "Portal#2026"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Confirmation message explaining which password applies.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "message": "Portal enabled. Client can log in with the password you set."
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients/{id}/portal-status": {
            "get": {
                "operationId": "get_api_clients_id_portal_status",
                "tags": [
                    "Customers"
                ],
                "summary": "Get client-portal status",
                "description": "Tells whether the customer has a client-portal login: `portal_enabled` (status = 1), `portal_email`, `has_password` and `invitation_pending` (an invite token was generated but not yet used).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "Api\\Portal\\PortalAdminController@getStatus",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAdminController.php#L19-L32",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "PortalClient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Portal status flags.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "portal_enabled": {},
                                        "portal_email": {},
                                        "has_password": {},
                                        "invitation_pending": {}
                                    }
                                },
                                "example": {
                                    "portal_enabled": true,
                                    "portal_email": "jane@acme.test",
                                    "has_password": true,
                                    "invitation_pending": false
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients_pay_due": {
            "post": {
                "operationId": "post_api_clients_pay_due",
                "tags": [
                    "Customers"
                ],
                "summary": "Pay a customer's outstanding due",
                "description": "Records a lump-sum payment from a customer and allocates it automatically:\n\n1. The **opening balance** is paid first (a `client_opening_balance_payments` row is created).\n2. The remainder is applied to **completed, unpaid or partially paid sales**, oldest first, creating one `payment_sales` row per sale and updating each sale's `paid_amount` / `payment_statut` (`partial` or `paid`).\n\nIf `account_id` is given, that treasury account's balance is increased by the amount received. Nothing happens when `amount <= 0`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@clients_pay_due",
                "x-source": "app/Http/Controllers/ClientController.php#L689-L792",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pay_due",
                        "slug": "pay_due",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "PaymentOpeningBalance",
                    "Account",
                    "Sale",
                    "PaymentSale"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to credit (optional)."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Total amount received."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Customer being paid for."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free-text note copied onto every generated payment."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id (Cash, Card, …)."
                                    }
                                }
                            },
                            "example": {
                                "client_id": 3,
                                "amount": 500,
                                "payment_method_id": 1,
                                "account_id": 1,
                                "notes": "Bank transfer ref 4471"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients_pay_return_due": {
            "post": {
                "operationId": "post_api_clients_pay_return_due",
                "tags": [
                    "Customers"
                ],
                "summary": "Refund a customer's sale-return due",
                "description": "Pays out money you owe a customer for **sale returns** that are not fully refunded. The amount is spread over the customer's unpaid sale returns in id order, creating a `payment_sale_returns` row per return and updating `paid_amount` / `payment_statut`. If `account_id` is given, the account balance is **decreased** (money going out).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@pay_sale_return_due",
                "x-source": "app/Http/Controllers/ClientController.php#L796-L855",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pay_sale_return_due",
                        "slug": "pay_sale_return_due",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "PaymentSaleReturns",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to debit (optional)."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Total amount refunded."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Customer to refund."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Note copied onto each generated payment."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id."
                                    }
                                }
                            },
                            "example": {
                                "client_id": 3,
                                "amount": 120,
                                "payment_method_id": 1,
                                "account_id": 1
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients_without_ecommerce": {
            "get": {
                "operationId": "get_api_clients_without_ecommerce",
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "List customers without a store account",
                "description": "Paginated list of customers that do not yet have an online-store login, so an account can be created for them. Rows contain `id, name, phone, code, email`. `clients_without_ecommerce` in the response is the total count of such customers (ignores filters).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@index",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L22-L83",
                "x-route-name": "clients_without_ecommerce.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "name",
                    "code",
                    "phone",
                    "email"
                ],
                "x-models": [
                    "Client"
                ],
                "x-notes": [
                    "`SortField` and `SortType` are passed straight to `ORDER BY`; always send both (e.g. `SortField=id&SortType=desc`) or the query fails."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on customer code."
                    },
                    {
                        "name": "email",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on email."
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on customer name (`LIKE`)."
                    },
                    {
                        "name": "phone",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on phone."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`clients[]`, `totalRows`, `clients_without_ecommerce`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "clients_without_ecommerce": {}
                                    }
                                },
                                "example": {
                                    "clients": [
                                        {
                                            "id": 8,
                                            "name": "John Smith",
                                            "phone": "0612345678",
                                            "code": 8,
                                            "email": "john@example.com"
                                        }
                                    ],
                                    "totalRows": 1,
                                    "clients_without_ecommerce": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_clients_without_ecommerce",
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "Create a store account for a customer",
                "description": "Creates an online-store login for an existing customer. The `username` is copied from the customer's name and the account is created active (`status = 1`). Fails with `403 {success:false}` when the customer already has an account. `email` must be unique across customers (other than this one) and store accounts.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@store",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L218-L259",
                "x-route-name": "clients_without_ecommerce.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Customers_add",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient",
                    "Client"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Id of the customer to attach the account to."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "ecommerce_clients,email ->whereNull",
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:clients,email ->whereNull->ignore",
                                            "unique:ecommerce_clients,email ->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Login email."
                                    },
                                    "password": {
                                        "type": "string",
                                        "minLength": 6,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "min:6"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Login password, min 6 chars."
                                    }
                                },
                                "required": [
                                    "email",
                                    "password"
                                ]
                            },
                            "example": {
                                "client_id": 8,
                                "email": "john@example.com",
                                "password": "secret123"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "`{ \"success\": false }` – the customer already has a store account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/clients_without_ecommerce/{clients_without_ecommerce}": {
            "delete": {
                "operationId": "delete_api_clients_without_ecommerce_clients_without_ecommerce",
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "Soft-delete a customer (legacy)",
                "description": "Despite its URL this endpoint soft-deletes the **customer** record (`clients.deleted_at`), not a store account. Prefer `DELETE /api/clients/{client}`, which also cleans up the linked account.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@destroy",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L330-L338",
                "x-route-name": "clients_without_ecommerce.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Customers_delete",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "clients_without_ecommerce",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_clients_without_ecommerce_clients_without_ecommerce",
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "(Not implemented) Get a store account",
                "description": "Resource stub with an empty body: the route exists but returns an empty `200` response. Use `GET /api/get_client_store_data/{id}` instead.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@show",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L263-L266",
                "x-route-name": "clients_without_ecommerce.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "clients_without_ecommerce",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_clients_without_ecommerce_clients_without_ecommerce",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "Update a store account by customer id",
                "description": "Updates the store account attached to a customer. The `email` is written to both the store account and the customer record. `NewPassword` is hashed and saved only when it is non-empty and different from the stored hash; send nothing, `null` or the string `\"null\"` to keep the current password.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@update",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L270-L326",
                "x-route-name": "clients_without_ecommerce.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient",
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "clients_without_ecommerce",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id (the account is looked up by `client_id`)."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "NewPassword": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "New password, or empty to keep the current one."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "ecommerce_clients,email ->ignore->whereNull",
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:clients,email ->ignore->whereNull",
                                            "unique:ecommerce_clients,email ->ignore->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New login email; unique across customers and store accounts."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "email": "john@example.com",
                                "NewPassword": ""
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_clients_without_ecommerce_clients_without_ecommerce",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "Update a store account by customer id",
                "description": "Updates the store account attached to a customer. The `email` is written to both the store account and the customer record. `NewPassword` is hashed and saved only when it is non-empty and different from the stored hash; send nothing, `null` or the string `\"null\"` to keep the current password.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@update",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L270-L326",
                "x-route-name": "clients_without_ecommerce.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient",
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "clients_without_ecommerce",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id (the account is looked up by `client_id`)."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "NewPassword": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "New password, or empty to keep the current one."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "ecommerce_clients,email ->ignore->whereNull",
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:clients,email ->ignore->whereNull",
                                            "unique:ecommerce_clients,email ->ignore->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New login email; unique across customers and store accounts."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "email": "john@example.com",
                                "NewPassword": ""
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/commission_programs": {
            "get": {
                "operationId": "get_api_commission_programs",
                "tags": [
                    "Commission Programs"
                ],
                "summary": "List commission programs",
                "description": "Paginated programs with `commission_rules_count` and `sale_commissions_count`. `search` matches name or description.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionProgramController@index",
                "x-source": "app/Http/Controllers/Commission/CommissionProgramController.php#L11-L43",
                "x-route-name": "commission_programs.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "CommissionProgram"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "is_active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on active flag."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `data.programs[]` and `data.totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_commission_programs",
                "tags": [
                    "Commission Programs"
                ],
                "summary": "Create a commission program",
                "description": "Creates a commission program: name, active flag, period and the calculation basis its rules will use.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionProgramController@store",
                "x-source": "app/Http/Controllers/Commission/CommissionProgramController.php#L45-L65",
                "x-route-name": "commission_programs.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "commissions_add",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionProgram"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Description (max 500)."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active (default true)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (max 192)."
                                    },
                                    "valid_from": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start of validity."
                                    },
                                    "valid_to": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:valid_from"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:valid_from"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End of validity (>= from)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Retail 2026",
                                "is_active": true,
                                "valid_from": "2026-01-01",
                                "valid_to": "2026-12-31"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the created program.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {}
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_programs/{commission_program}": {
            "delete": {
                "operationId": "delete_api_commission_programs_commission_program",
                "tags": [
                    "Commission Programs"
                ],
                "summary": "Delete a commission program",
                "description": "Soft-deletes the program and hides its rules. Commissions already calculated are kept.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionProgramController@destroy",
                "x-source": "app/Http/Controllers/Commission/CommissionProgramController.php#L97-L103",
                "x-route-name": "commission_programs.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "commissions_delete",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionProgram"
                ],
                "parameters": [
                    {
                        "name": "commission_program",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Program id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope, `data` null.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "nullable": true,
                                            "type": "string"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_commission_programs_commission_program",
                "tags": [
                    "Commission Programs"
                ],
                "summary": "Get a commission program",
                "description": "Program with its rules (and each rule's agent).",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionProgramController@show",
                "x-source": "app/Http/Controllers/Commission/CommissionProgramController.php#L67-L72",
                "x-route-name": "commission_programs.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionProgram"
                ],
                "parameters": [
                    {
                        "name": "commission_program",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Program id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with the program.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {}
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_commission_programs_commission_program",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Commission Programs"
                ],
                "summary": "Update a commission program",
                "description": "Updates a program with the same fields as creation.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionProgramController@update",
                "x-source": "app/Http/Controllers/Commission/CommissionProgramController.php#L74-L95",
                "x-route-name": "commission_programs.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionProgram"
                ],
                "parameters": [
                    {
                        "name": "commission_program",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Program id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "valid_from": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "From."
                                    },
                                    "valid_to": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:valid_from"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:valid_from"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "To."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the updated program.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_commission_programs_commission_program",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Commission Programs"
                ],
                "summary": "Update a commission program",
                "description": "Updates a program with the same fields as creation.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionProgramController@update",
                "x-source": "app/Http/Controllers/Commission/CommissionProgramController.php#L74-L95",
                "x-route-name": "commission_programs.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionProgram"
                ],
                "parameters": [
                    {
                        "name": "commission_program",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Program id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "valid_from": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "From."
                                    },
                                    "valid_to": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:valid_from"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:valid_from"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "To."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the updated program.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/commission_receipts": {
            "get": {
                "operationId": "get_api_commission_receipts",
                "tags": [
                    "Commission Receipts"
                ],
                "summary": "List commission receipts",
                "description": "Paginated receipts (default sort `paid_at desc`) with agent and payment method. `search` matches Ref.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionReceiptController@index",
                "x-source": "app/Http/Controllers/Commission/CommissionReceiptController.php#L20-L55",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "CommissionReceipt"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Paid from."
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Paid to."
                    },
                    {
                        "name": "sales_agent_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Agent filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `data.receipts[]` and `data.totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_commission_receipts",
                "tags": [
                    "Commission Receipts"
                ],
                "summary": "Pay out commissions",
                "description": "Creates the receipt and marks the listed commissions `paid`. `Ref` is generated when omitted.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionReceiptController@store",
                "x-source": "app/Http/Controllers/Commission/CommissionReceiptController.php#L57-L86",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "commissions_add",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "Ref": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Receipt reference."
                                    },
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount paid."
                                    },
                                    "commission_ids": {
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Approved commission ids to pay.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "paid_at": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Payment date."
                                    },
                                    "payment_method_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "payment_methods,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:payment_methods,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Payment method."
                                    },
                                    "sales_agent_id": {
                                        "type": "integer",
                                        "x-exists": "sales_agents,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:sales_agents,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Agent being paid."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "commission_ids",
                                    "paid_at",
                                    "sales_agent_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the receipt.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_receipts/new_ref": {
            "get": {
                "operationId": "get_api_commission_receipts_new_ref",
                "tags": [
                    "Commission Receipts"
                ],
                "summary": "Next receipt reference",
                "description": "Next receipt Ref for forms (support endpoint).",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionReceiptController@getNewRef",
                "x-source": "app/Http/Controllers/Commission/CommissionReceiptController.php#L97-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `data.Ref`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_receipts/{id}": {
            "get": {
                "operationId": "get_api_commission_receipts_id",
                "tags": [
                    "Commission Receipts"
                ],
                "summary": "Get a commission receipt",
                "description": "Receipt with agent, payment method and the paid commissions (with their sale and rule).",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionReceiptController@show",
                "x-source": "app/Http/Controllers/Commission/CommissionReceiptController.php#L88-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionReceipt"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Receipt id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with the receipt.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {}
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_report": {
            "get": {
                "operationId": "get_api_commission_report",
                "tags": [
                    "Commission Reports"
                ],
                "summary": "Commission ledger",
                "description": "Paginated sale commissions (default `calculated_at desc`) with sale, agent, program, rule and receipt.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionReportController@index",
                "x-source": "app/Http/Controllers/Commission/CommissionReportController.php#L13-L59",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SaleCommission"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "commission_program_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Program."
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Calculated from."
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Calculated to."
                    },
                    {
                        "name": "sale_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sale."
                    },
                    {
                        "name": "sales_agent_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Agent."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `approved`, `paid`, `cancelled`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `data.commissions[]` and `data.totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_report/by_agent": {
            "get": {
                "operationId": "get_api_commission_report_by_agent",
                "tags": [
                    "Commission Reports"
                ],
                "summary": "Commissions per agent",
                "description": "Per agent: `total_commission`, `pending`, `approved`, `paid`.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionReportController@byAgent",
                "x-source": "app/Http/Controllers/Commission/CommissionReportController.php#L95-L116",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SaleCommission"
                ],
                "parameters": [
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `by_agent[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_report/summary": {
            "get": {
                "operationId": "get_api_commission_report_summary",
                "tags": [
                    "Commission Reports"
                ],
                "summary": "Commission summary",
                "description": "`by_status` (count and total per status) and `totals` (`pending_total`, `approved_total`, `paid_total`, `grand_total`, `total_count`).",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionReportController@summary",
                "x-source": "app/Http/Controllers/Commission/CommissionReportController.php#L61-L93",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SaleCommission"
                ],
                "parameters": [
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "sales_agent_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Agent."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `by_status` and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_rules": {
            "get": {
                "operationId": "get_api_commission_rules",
                "tags": [
                    "Commission Rules"
                ],
                "summary": "List commission rules",
                "description": "Paginated rules (default sort `priority desc`) with program and agent.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionRuleController@index",
                "x-source": "app/Http/Controllers/Commission/CommissionRuleController.php#L12-L44",
                "x-route-name": "commission_rules.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "CommissionRule"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "commission_program_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Program filter."
                    },
                    {
                        "name": "is_active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Active flag."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `data.rules[]` and `data.totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_commission_rules",
                "tags": [
                    "Commission Rules"
                ],
                "summary": "Create a commission rule",
                "description": "Adds a rule to a program: scope (all products / category / product / agent), rate type (percentage or fixed) and value, optional minimum sale amount and priority.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionRuleController@store",
                "x-source": "app/Http/Controllers/Commission/CommissionRuleController.php#L46-L78",
                "x-route-name": "commission_rules.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "commissions_add",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionRule"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "applies_to": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "all_agents",
                                            "specific_agent"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:all_agents,specific_agent"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`all_agents` or `specific_agent`."
                                    },
                                    "commission_program_id": {
                                        "type": "integer",
                                        "x-exists": "commission_programs,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:commission_programs,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Program."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active (default true)."
                                    },
                                    "max_cap": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Maximum commission per sale."
                                    },
                                    "min_threshold": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Minimum sale amount for the rule to apply."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rule name."
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Higher runs first."
                                    },
                                    "sales_agent_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "sales_agents,id",
                                        "x-conditional": [
                                            "required_if:applies_to,specific_agent"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "required_if:applies_to,specific_agent",
                                            "integer",
                                            "exists:sales_agents,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Agent (required for `specific_agent`)."
                                    },
                                    "source": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sale_total",
                                            "paid_amount"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sale_total,paid_amount"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`sale_total` or `paid_amount`."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:percentage,fixed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`percentage` or `fixed`."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Percent or fixed amount."
                                    }
                                },
                                "required": [
                                    "applies_to",
                                    "commission_program_id",
                                    "name",
                                    "source",
                                    "type",
                                    "value"
                                ]
                            },
                            "example": {
                                "commission_program_id": 1,
                                "name": "5% on paid amount",
                                "type": "percentage",
                                "source": "paid_amount",
                                "value": 5,
                                "min_threshold": 100,
                                "max_cap": 500,
                                "applies_to": "all_agents",
                                "priority": 10,
                                "is_active": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the created rule.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commission_rules/{commission_rule}": {
            "delete": {
                "operationId": "delete_api_commission_rules_commission_rule",
                "tags": [
                    "Commission Rules"
                ],
                "summary": "Delete a commission rule",
                "description": "Soft-deletes a rule.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionRuleController@destroy",
                "x-source": "app/Http/Controllers/Commission/CommissionRuleController.php#L122-L128",
                "x-route-name": "commission_rules.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "commissions_delete",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionRule"
                ],
                "parameters": [
                    {
                        "name": "commission_rule",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Rule id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope, `data` null.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "nullable": true,
                                            "type": "string"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_commission_rules_commission_rule",
                "tags": [
                    "Commission Rules"
                ],
                "summary": "Get a commission rule",
                "description": "One rule with its program and scope details.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionRuleController@show",
                "x-source": "app/Http/Controllers/Commission/CommissionRuleController.php#L80-L85",
                "x-route-name": "commission_rules.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionRule"
                ],
                "parameters": [
                    {
                        "name": "commission_rule",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Rule id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with the rule.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {}
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_commission_rules_commission_rule",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Commission Rules"
                ],
                "summary": "Update a commission rule",
                "description": "Updates a rule with the same fields as creation.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionRuleController@update",
                "x-source": "app/Http/Controllers/Commission/CommissionRuleController.php#L87-L120",
                "x-route-name": "commission_rules.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionRule"
                ],
                "parameters": [
                    {
                        "name": "commission_rule",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Rule id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "applies_to": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "all_agents",
                                            "specific_agent"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:all_agents,specific_agent"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Scope."
                                    },
                                    "commission_program_id": {
                                        "type": "integer",
                                        "x-exists": "commission_programs,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:commission_programs,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Program."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "max_cap": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cap."
                                    },
                                    "min_threshold": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Threshold."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Priority."
                                    },
                                    "sales_agent_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "sales_agents,id",
                                        "x-conditional": [
                                            "required_if:applies_to,specific_agent"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "required_if:applies_to,specific_agent",
                                            "integer",
                                            "exists:sales_agents,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Agent."
                                    },
                                    "source": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sale_total",
                                            "paid_amount"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sale_total,paid_amount"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:percentage,fixed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Value."
                                    }
                                },
                                "required": [
                                    "applies_to",
                                    "commission_program_id",
                                    "name",
                                    "source",
                                    "type",
                                    "value"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the updated rule.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_commission_rules_commission_rule",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Commission Rules"
                ],
                "summary": "Update a commission rule",
                "description": "Updates a rule with the same fields as creation.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionRuleController@update",
                "x-source": "app/Http/Controllers/Commission/CommissionRuleController.php#L87-L120",
                "x-route-name": "commission_rules.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "CommissionRule"
                ],
                "parameters": [
                    {
                        "name": "commission_rule",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Rule id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "applies_to": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "all_agents",
                                            "specific_agent"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:all_agents,specific_agent"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Scope."
                                    },
                                    "commission_program_id": {
                                        "type": "integer",
                                        "x-exists": "commission_programs,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:commission_programs,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Program."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "max_cap": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cap."
                                    },
                                    "min_threshold": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Threshold."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Priority."
                                    },
                                    "sales_agent_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "sales_agents,id",
                                        "x-conditional": [
                                            "required_if:applies_to,specific_agent"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "required_if:applies_to,specific_agent",
                                            "integer",
                                            "exists:sales_agents,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Agent."
                                    },
                                    "source": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sale_total",
                                            "paid_amount"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sale_total,paid_amount"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:percentage,fixed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Value."
                                    }
                                },
                                "required": [
                                    "applies_to",
                                    "commission_program_id",
                                    "name",
                                    "source",
                                    "type",
                                    "value"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the updated rule.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/commissions/approve": {
            "post": {
                "operationId": "post_api_commissions_approve",
                "tags": [
                    "Commissions"
                ],
                "summary": "Approve commissions",
                "description": "Moves the listed `pending` commissions to `approved`.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionController@approve",
                "x-source": "app/Http/Controllers/Commission/CommissionController.php#L34-L45",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SaleCommission"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "commission_ids": {
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Sale-commission ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "required": [
                                    "commission_ids"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with `updated_count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commissions/calculate_for_sale/{saleId}": {
            "post": {
                "operationId": "post_api_commissions_calculate_for_sale_saleId",
                "tags": [
                    "Commissions"
                ],
                "summary": "Calculate commissions for a sale",
                "description": "Applies the active rules to the sale's agent. Idempotent — existing commissions are not duplicated.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionController@calculateForSale",
                "x-source": "app/Http/Controllers/Commission/CommissionController.php#L22-L31",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "commissions_add",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "saleId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `created_count` and `commissions[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/commissions/cancel": {
            "post": {
                "operationId": "post_api_commissions_cancel",
                "tags": [
                    "Commissions"
                ],
                "summary": "Cancel commissions",
                "description": "Moves `pending` or `approved` commissions to `cancelled`.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\CommissionController@cancel",
                "x-source": "app/Http/Controllers/Commission/CommissionController.php#L48-L59",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SaleCommission"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "commission_ids": {
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Sale-commission ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "required": [
                                    "commission_ids"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with `updated_count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/company": {
            "get": {
                "operationId": "get_api_company",
                "tags": [
                    "Companies"
                ],
                "summary": "List companies",
                "description": "Paginated companies. `search` matches name, phone, country or email.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@index",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L14-L50",
                "x-route-name": "company.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "company",
                        "policy": "CompanyPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_company",
                "tags": [
                    "Companies"
                ],
                "summary": "Create a company",
                "description": "Creates an HR company (legal entity) that employees, departments and designations belong to.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@store",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L54-L70",
                "x-route-name": "company.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "company",
                        "policy": "CompanyPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Contact email."
                                    },
                                    "name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company name."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Stocky HQ",
                                "email": "hr@stocky.test",
                                "phone": "+212600000000",
                                "country": "Morocco"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/company/delete/by_selection": {
            "post": {
                "operationId": "post_api_company_delete_by_selection",
                "tags": [
                    "Companies"
                ],
                "summary": "Delete selected companies",
                "description": "Bulk soft-delete of companies by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L115-L128",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "company",
                        "policy": "CompanyPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company ids to soft-delete.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/company/{company}": {
            "delete": {
                "operationId": "delete_api_company_company",
                "tags": [
                    "Companies"
                ],
                "summary": "Delete a company",
                "description": "Soft-deletes the company.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@destroy",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L102-L111",
                "x-route-name": "company.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "company",
                        "policy": "CompanyPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "company",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Company id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_company_company",
                "tags": [
                    "Companies"
                ],
                "summary": "Get a company (not implemented)",
                "description": "**Not implemented** — the method body is empty and returns an empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@show",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L74-L78",
                "x-route-name": "company.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "company",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Company id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_company_company",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Companies"
                ],
                "summary": "Update a company",
                "description": "Updates a company with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@update",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L82-L98",
                "x-route-name": "company.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "company",
                        "policy": "CompanyPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "company",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Company id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_company_company",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Companies"
                ],
                "summary": "Update a company",
                "description": "Updates a company with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@update",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L82-L98",
                "x-route-name": "company.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "company",
                        "policy": "CompanyPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "company",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Company id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/contracts": {
            "get": {
                "operationId": "get_api_contracts",
                "tags": [
                    "Contracts"
                ],
                "summary": "List contracts",
                "description": "Paginated contracts with client, employee and project, plus the `clients`, `employees`, `projects` lookups. `search` matches contract number, subject or client name.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@index",
                "x-source": "app/Http/Controllers/ContractController.php#L26-L93",
                "x-route-name": "contracts.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "contract_number",
                    "client_id",
                    "status",
                    "type",
                    "project_id"
                ],
                "x-models": [
                    "Contract",
                    "Client",
                    "Employee",
                    "Project"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Client filter."
                    },
                    {
                        "name": "contract_number",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter (LIKE) on number."
                    },
                    {
                        "name": "project_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Project filter."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Status filter."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Type filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`contracts[]`, `totalRows`, `clients[]`, `employees[]`, `projects[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "contracts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_contracts",
                "tags": [
                    "Contracts"
                ],
                "summary": "Create a contract",
                "description": "Creates a contract: title, type, counterparty (customer or supplier), value, start/end dates, renewal settings, owner, tags and body text (rendered from a template when `template_id` is given). Returns the created contract.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@store",
                "x-source": "app/Http/Controllers/ContractController.php#L111-L146",
                "x-route-name": "contracts.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "clients,id",
                                        "x-conditional": [
                                            "required_if:party_type,customer"
                                        ],
                                        "x-laravel-rules": [
                                            "required_if:party_type,customer",
                                            "nullable",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Client (required when party_type = customer)."
                                    },
                                    "contract_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Number (auto-generated when empty)."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Body / terms (HTML allowed)."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-conditional": [
                                            "required_if:party_type,employee"
                                        ],
                                        "x-laravel-rules": [
                                            "required_if:party_type,employee",
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee (required when party_type = employee)."
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "date",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End (>= start)."
                                    },
                                    "hide_from_customer": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide from the client portal.",
                                        "type": "boolean"
                                    },
                                    "party_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "customer",
                                            "employee"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:customer,employee"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`customer` or `employee`."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Linked project."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "active",
                                            "expired",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:draft,active,expired,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`draft`, `active`, `expired`, `cancelled`."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject (max 255)."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free-text type (e.g. `Service`, `Lease`)."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Contract value."
                                    }
                                },
                                "required": [
                                    "end_date",
                                    "party_type",
                                    "start_date",
                                    "status",
                                    "subject",
                                    "value"
                                ]
                            },
                            "example": {
                                "party_type": "customer",
                                "client_id": 4,
                                "project_id": 3,
                                "subject": "Annual maintenance",
                                "value": 24000,
                                "type": "Service",
                                "start_date": "2026-10-01",
                                "end_date": "2027-09-30",
                                "status": "active",
                                "description": "<p>Terms…</p>",
                                "hide_from_customer": false
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "start_date.required": {
                                            "type": "string",
                                            "example": "Start date is required."
                                        },
                                        "start_date.date": {
                                            "type": "string",
                                            "example": "Start date is not a valid date."
                                        },
                                        "end_date.required": {
                                            "type": "string",
                                            "example": "Finish date is required."
                                        },
                                        "end_date.date": {
                                            "type": "string",
                                            "example": "Finish date is not a valid date."
                                        },
                                        "end_date.after_or_equal": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts-templates": {
            "get": {
                "operationId": "get_api_contracts_templates",
                "tags": [
                    "Contracts"
                ],
                "summary": "List contract templates",
                "description": "All contract templates with their placeholders. Templates are reusable bodies inserted into new contracts.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@templatesIndex",
                "x-source": "app/Http/Controllers/ContractController.php#L587-L592",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractTemplate"
                ],
                "responses": {
                    "200": {
                        "description": "`templates[] {id, name, content}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "templates": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_contracts_templates",
                "tags": [
                    "Contracts"
                ],
                "summary": "Create a contract template",
                "description": "Creates a template (name, type, body with `{{placeholders}}`).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@templatesStore",
                "x-source": "app/Http/Controllers/ContractController.php#L601-L607",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractTemplate"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "content": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "HTML with merge fields."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (max 255)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `template`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "template": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts-templates/{templateId}": {
            "delete": {
                "operationId": "delete_api_contracts_templates_templateId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Delete a contract template",
                "description": "Deletes a template. Contracts already created from it keep their own copy of the text.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@templatesDestroy",
                "x-source": "app/Http/Controllers/ContractController.php#L617-L622",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractTemplate"
                ],
                "parameters": [
                    {
                        "name": "templateId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_contracts_templates_templateId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Get a contract template",
                "description": "One template with its body.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@templatesShow",
                "x-source": "app/Http/Controllers/ContractController.php#L594-L599",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractTemplate"
                ],
                "parameters": [
                    {
                        "name": "templateId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`template`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "template": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_contracts_templates_templateId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Update a contract template",
                "description": "Updates a template's name, type or body.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@templatesUpdate",
                "x-source": "app/Http/Controllers/ContractController.php#L609-L615",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractTemplate"
                ],
                "parameters": [
                    {
                        "name": "templateId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "content": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "HTML."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Name."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/create": {
            "get": {
                "operationId": "get_api_contracts_create",
                "tags": [
                    "Contracts"
                ],
                "summary": "Create-form data for a contract",
                "description": "Lookup data for the contract form: customers, suppliers, templates, users and contract types.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@create",
                "x-source": "app/Http/Controllers/ContractController.php#L95-L109",
                "x-route-name": "contracts.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Employee",
                    "Project",
                    "Contract"
                ],
                "responses": {
                    "200": {
                        "description": "`clients[]`, `employees[]`, `projects[]`, `next_contract_number`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "next_contract_number": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/dashboard": {
            "get": {
                "operationId": "get_api_contracts_dashboard",
                "tags": [
                    "Contracts"
                ],
                "summary": "Contracts dashboard",
                "description": "`count_active`, `count_expired`, `count_about_to_expire` (next 30 days), `count_recently_added` (7 days), `count_trash` and `charts` (count and value by type).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@dashboard",
                "x-source": "app/Http/Controllers/ContractController.php#L281-L323",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count_active": {},
                                        "count_expired": {},
                                        "count_about_to_expire": {},
                                        "count_recently_added": {},
                                        "count_trash": {},
                                        "charts": {
                                            "type": "object",
                                            "properties": {
                                                "by_type": {},
                                                "value_by_type": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/delete/by_selection": {
            "post": {
                "operationId": "post_api_contracts_delete_by_selection",
                "tags": [
                    "Contracts"
                ],
                "summary": "Delete selected contracts",
                "description": "Bulk soft-delete of contracts by `selectedIds`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@delete_by_selection",
                "x-source": "app/Http/Controllers/ContractController.php#L271-L279",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Contract ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/merge-fields": {
            "get": {
                "operationId": "get_api_contracts_merge_fields",
                "tags": [
                    "Contracts"
                ],
                "summary": "List template merge fields",
                "description": "Placeholders (`{contract_number}`, `{customer_name}`, `{project_name}`, `{contract_value}`, `{start_date}`, `{signer_name}`, …) accepted in template content.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@mergeFields",
                "x-source": "app/Http/Controllers/ContractController.php#L404-L428",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`merge_fields[] {key, label}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "merge_fields": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contractId}/attachments/{attachmentId}": {
            "delete": {
                "operationId": "delete_api_contracts_contractId_attachments_attachmentId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Delete a contract attachment",
                "description": "Removes an attachment and deletes the stored file.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@attachmentsDestroy",
                "x-source": "app/Http/Controllers/ContractController.php#L450-L457",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractAttachment"
                ],
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "attachmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Attachment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contractId}/attachments/{attachmentId}/download": {
            "get": {
                "operationId": "get_api_contracts_contractId_attachments_attachmentId_download",
                "tags": [
                    "Contracts"
                ],
                "summary": "Download a contract attachment",
                "description": "Downloads the attachment file with its original name.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@attachmentsDownload",
                "x-source": "app/Http/Controllers/ContractController.php#L459-L468",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractAttachment"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "attachmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Attachment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contractId}/comments/{commentId}": {
            "delete": {
                "operationId": "delete_api_contracts_contractId_comments_commentId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Delete a contract comment",
                "description": "Deletes a comment (author or user with contract edit rights).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@commentsDestroy",
                "x-source": "app/Http/Controllers/ContractController.php#L490-L495",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractComment"
                ],
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "commentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Comment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contractId}/notes/{noteId}": {
            "delete": {
                "operationId": "delete_api_contracts_contractId_notes_noteId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Delete an internal note",
                "description": "Deletes an internal note.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@notesDestroy",
                "x-source": "app/Http/Controllers/ContractController.php#L579-L584",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractNote"
                ],
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "noteId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Note id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contractId}/tasks/{taskId}": {
            "delete": {
                "operationId": "delete_api_contracts_contractId_tasks_taskId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Delete a contract task",
                "description": "Deletes a task attached to the contract.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@tasksDestroy",
                "x-source": "app/Http/Controllers/ContractController.php#L552-L557",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractTask"
                ],
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "taskId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Task id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_contracts_contractId_tasks_taskId",
                "tags": [
                    "Contracts"
                ],
                "summary": "Update a contract task",
                "description": "Updates a contract task (title, assignee, due date, status).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@tasksUpdate",
                "x-source": "app/Http/Controllers/ContractController.php#L544-L550",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "ContractTask"
                ],
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "taskId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Task id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "due_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contractId}/templates/{templateId}/pdf": {
            "get": {
                "operationId": "get_api_contracts_contractId_templates_templateId_pdf",
                "tags": [
                    "Contracts"
                ],
                "summary": "Export a rendered template as PDF",
                "description": "Render a template merged with a contract's data as a PDF (preview or download).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@templatePdf",
                "x-source": "app/Http/Controllers/ContractController.php#L380-L402",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "ContractTemplate"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "templateId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    },
                    {
                        "name": "preview",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` streams inline."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contractId}/templates/{templateId}/render": {
            "get": {
                "operationId": "get_api_contracts_contractId_templates_templateId_render",
                "tags": [
                    "Contracts"
                ],
                "summary": "Render a template for a contract",
                "description": "Returns the template HTML with merge fields replaced by the contract's data.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@templateRender",
                "x-source": "app/Http/Controllers/ContractController.php#L625-L632",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "ContractTemplate"
                ],
                "parameters": [
                    {
                        "name": "contractId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "templateId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`content` (HTML).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "content": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{contract}": {
            "delete": {
                "operationId": "delete_api_contracts_contract",
                "tags": [
                    "Contracts"
                ],
                "summary": "Delete a contract",
                "description": "Soft-deletes (moves to trash).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@destroy",
                "x-source": "app/Http/Controllers/ContractController.php#L262-L269",
                "x-route-name": "contracts.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "contract",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_contracts_contract",
                "tags": [
                    "Contracts"
                ],
                "summary": "Get a contract",
                "description": "Full contract with party names, project, attachments, comments, renewals, tasks, notes and signature fields.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@show",
                "x-source": "app/Http/Controllers/ContractController.php#L148-L201",
                "x-route-name": "contracts.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "contract",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`contract`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "contract": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_contracts_contract",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Contracts"
                ],
                "summary": "Update a contract",
                "description": "Updates a contract with the same fields as creation. Changing the status to `signed`/`active` records the date; changing dates recomputes the expiry reminders.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@update",
                "x-source": "app/Http/Controllers/ContractController.php#L223-L260",
                "x-route-name": "contracts.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "contract",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Contract id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "clients,id",
                                        "x-conditional": [
                                            "required_if:party_type,customer"
                                        ],
                                        "x-laravel-rules": [
                                            "required_if:party_type,customer",
                                            "nullable",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Client."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Body."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-conditional": [
                                            "required_if:party_type,employee"
                                        ],
                                        "x-laravel-rules": [
                                            "required_if:party_type,employee",
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "date",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "hide_from_customer": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide from portal.",
                                        "type": "boolean"
                                    },
                                    "party_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "customer",
                                            "employee"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:customer,employee"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Party type."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "signed_at": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Signature timestamp.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "signed_ip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Signer IP."
                                    },
                                    "signer_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Name of the signer (e-signature)."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "active",
                                            "expired",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:draft,active,expired,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Value."
                                    }
                                },
                                "required": [
                                    "end_date",
                                    "party_type",
                                    "start_date",
                                    "status",
                                    "subject",
                                    "value"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "start_date.required": {
                                            "type": "string",
                                            "example": "Start date is required."
                                        },
                                        "start_date.date": {
                                            "type": "string",
                                            "example": "Start date is not a valid date."
                                        },
                                        "end_date.required": {
                                            "type": "string",
                                            "example": "Finish date is required."
                                        },
                                        "end_date.date": {
                                            "type": "string",
                                            "example": "Finish date is not a valid date."
                                        },
                                        "end_date.after_or_equal": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_contracts_contract",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Contracts"
                ],
                "summary": "Update a contract",
                "description": "Updates a contract with the same fields as creation. Changing the status to `signed`/`active` records the date; changing dates recomputes the expiry reminders.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@update",
                "x-source": "app/Http/Controllers/ContractController.php#L223-L260",
                "x-route-name": "contracts.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "contract",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Contract id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "clients,id",
                                        "x-conditional": [
                                            "required_if:party_type,customer"
                                        ],
                                        "x-laravel-rules": [
                                            "required_if:party_type,customer",
                                            "nullable",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Client."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Body."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-conditional": [
                                            "required_if:party_type,employee"
                                        ],
                                        "x-laravel-rules": [
                                            "required_if:party_type,employee",
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "date",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "hide_from_customer": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide from portal.",
                                        "type": "boolean"
                                    },
                                    "party_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "customer",
                                            "employee"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:customer,employee"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Party type."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "signed_at": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Signature timestamp.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "signed_ip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Signer IP."
                                    },
                                    "signer_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Name of the signer (e-signature)."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "active",
                                            "expired",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:draft,active,expired,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Value."
                                    }
                                },
                                "required": [
                                    "end_date",
                                    "party_type",
                                    "start_date",
                                    "status",
                                    "subject",
                                    "value"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "start_date.required": {
                                            "type": "string",
                                            "example": "Start date is required."
                                        },
                                        "start_date.date": {
                                            "type": "string",
                                            "example": "Start date is not a valid date."
                                        },
                                        "end_date.required": {
                                            "type": "string",
                                            "example": "Finish date is required."
                                        },
                                        "end_date.date": {
                                            "type": "string",
                                            "example": "Finish date is not a valid date."
                                        },
                                        "end_date.after_or_equal": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/contracts/{contract}/edit": {
            "get": {
                "operationId": "get_api_contracts_contract_edit",
                "tags": [
                    "Contracts"
                ],
                "summary": "Edit-form data for a contract",
                "description": "The contract plus the lookups needed by the edit form.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@edit",
                "x-source": "app/Http/Controllers/ContractController.php#L203-L221",
                "x-route-name": "contracts.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "Client",
                    "Employee",
                    "Project"
                ],
                "parameters": [
                    {
                        "name": "contract",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`contract`, `clients[]`, `employees[]`, `projects[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "contract": {},
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{id}/attachments": {
            "get": {
                "operationId": "get_api_contracts_id_attachments",
                "tags": [
                    "Contracts"
                ],
                "summary": "List contract attachments",
                "description": "Files attached to the contract with size, type, uploader and date.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@attachmentsIndex",
                "x-source": "app/Http/Controllers/ContractController.php#L431-L437",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`attachments[] {id, file_name, file_path}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "attachments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_contracts_id_attachments",
                "tags": [
                    "Contracts"
                ],
                "summary": "Upload a contract attachment",
                "description": "Uploads one file (multipart `file`) and links it to the contract.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@attachmentsStore",
                "x-source": "app/Http/Controllers/ContractController.php#L439-L448",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "ContractAttachment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "maxLength": 10240,
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "max:10240"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "File, max 10 MB."
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and stored `path`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "path": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{id}/comments": {
            "get": {
                "operationId": "get_api_contracts_id_comments",
                "tags": [
                    "Contracts"
                ],
                "summary": "List contract comments",
                "description": "Comment thread of the contract, oldest first, with author.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@commentsIndex",
                "x-source": "app/Http/Controllers/ContractController.php#L471-L478",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`comments[] {id, body, user_id, user_name, created_at}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "comments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_contracts_id_comments",
                "tags": [
                    "Contracts"
                ],
                "summary": "Add a contract comment",
                "description": "Adds a comment (`body`). Mentioned users are notified.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@commentsStore",
                "x-source": "app/Http/Controllers/ContractController.php#L480-L488",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "ContractComment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "body": {
                                        "type": "string",
                                        "maxLength": 5000,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:5000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Comment text (max 5000)."
                                    }
                                },
                                "required": [
                                    "body"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the `comment`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "comment": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "body": {},
                                                "user_name": {},
                                                "created_at": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{id}/notes": {
            "get": {
                "operationId": "get_api_contracts_id_notes",
                "tags": [
                    "Contracts"
                ],
                "summary": "List internal notes",
                "description": "Internal notes (not visible to the counterparty in the portal).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@notesIndex",
                "x-source": "app/Http/Controllers/ContractController.php#L560-L567",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`notes[] {id, content, user_name, created_at}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "notes": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_contracts_id_notes",
                "tags": [
                    "Contracts"
                ],
                "summary": "Add an internal note",
                "description": "Adds an internal note (`body`).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@notesStore",
                "x-source": "app/Http/Controllers/ContractController.php#L569-L577",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "ContractNote"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "content": {
                                        "type": "string",
                                        "maxLength": 10000,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:10000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Note text (max 10000)."
                                    }
                                },
                                "required": [
                                    "content"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the `note`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "note": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "content": {},
                                                "user_name": {},
                                                "created_at": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{id}/pdf": {
            "get": {
                "operationId": "get_api_contracts_id_pdf",
                "tags": [
                    "Contracts"
                ],
                "summary": "Contract PDF",
                "description": "Renders the contract sheet (party, value, dates, description, signature block).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@pdf",
                "x-source": "app/Http/Controllers/ContractController.php#L325-L377",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "preview",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` streams inline instead of downloading."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{id}/renewals": {
            "get": {
                "operationId": "get_api_contracts_id_renewals",
                "tags": [
                    "Contracts"
                ],
                "summary": "List renewals",
                "description": "Renewal history: each renewal with previous/new end dates, value and the user who renewed.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@renewalsIndex",
                "x-source": "app/Http/Controllers/ContractController.php#L498-L504",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`renewals[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "renewals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_contracts_id_renewals",
                "tags": [
                    "Contracts"
                ],
                "summary": "Record a renewal",
                "description": "Adds a renewal entry; it does **not** change the contract's own `end_date`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@renewalsStore",
                "x-source": "app/Http/Controllers/ContractController.php#L506-L518",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "ContractRenewal"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "new_end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New end date."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "renewal_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date the renewal was agreed."
                                    }
                                },
                                "required": [
                                    "new_end_date",
                                    "renewal_date"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/contracts/{id}/tasks": {
            "get": {
                "operationId": "get_api_contracts_id_tasks",
                "tags": [
                    "Contracts"
                ],
                "summary": "List contract tasks",
                "description": "Tasks attached to the contract with assignee, due date and status.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@tasksIndex",
                "x-source": "app/Http/Controllers/ContractController.php#L521-L527",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`tasks[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "tasks": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_contracts_id_tasks",
                "tags": [
                    "Contracts"
                ],
                "summary": "Add a contract task",
                "description": "Adds a task (title, description, assignee, due date, priority).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ContractController@tasksStore",
                "x-source": "app/Http/Controllers/ContractController.php#L529-L542",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "contracts",
                        "policy": "ContractPolicy"
                    }
                ],
                "x-models": [
                    "Contract",
                    "ContractTask"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "in_progress",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:pending,in_progress,completed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`pending` (default), `in_progress`, `completed`, `cancelled`."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 255)."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the `task`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "task": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/convert_to_sale_data/{id}": {
            "get": {
                "operationId": "get_api_convert_to_sale_data_id",
                "tags": [
                    "Sales"
                ],
                "summary": "Get quotation data to convert into a sale",
                "description": "Loads a quotation in *sale form* shape so it can be saved as a sale: `sale` header (`client_id, warehouse_id, date, tax_rate, TaxNet, discount, shipping, notes, quotation_id`), `details[]` lines with current stock, and the `clients`, `warehouses`, `sales_agents` lookups. Requires `Quotations_edit`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@Elemens_Change_To_Sale",
                "x-source": "app/Http/Controllers/SalesController.php#L3222-L3414",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Quotations_edit",
                        "policy": "QuotationPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "UserWarehouse",
                    "Client",
                    "Warehouse",
                    "Unit",
                    "product_warehouse",
                    "ProductVariant",
                    "SalesAgent"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Quotation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale`, `details[]`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale": {},
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales_agents": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/core/get_departments_by_company": {
            "get": {
                "operationId": "get_api_core_get_departments_by_company",
                "tags": [
                    "HR Lookups"
                ],
                "summary": "Departments of a company",
                "description": "Departments belonging to a company, for cascading selects. Pass `id` (company ID); returns `{id, department}` pairs.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CoreController@Get_departments_by_company",
                "x-source": "app/Http/Controllers/hrm/CoreController.php#L21-L26",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Department"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Company id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of departments.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/core/get_designations_by_department": {
            "get": {
                "operationId": "get_api_core_get_designations_by_department",
                "tags": [
                    "HR Lookups"
                ],
                "summary": "Designations of a department",
                "description": "Designations belonging to a department, for cascading selects. Pass `id` (department ID).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CoreController@Get_designations_by_department",
                "x-source": "app/Http/Controllers/hrm/CoreController.php#L14-L19",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Designation"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of designations.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/core/get_employees_by_company": {
            "get": {
                "operationId": "get_api_core_get_employees_by_company",
                "tags": [
                    "HR Lookups"
                ],
                "summary": "Employees of a company",
                "description": "`{id, username}` list.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CoreController@Get_employees_by_company",
                "x-source": "app/Http/Controllers/hrm/CoreController.php#L35-L40",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Company id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/core/get_office_shift_by_company": {
            "get": {
                "operationId": "get_api_core_get_office_shift_by_company",
                "tags": [
                    "HR Lookups"
                ],
                "summary": "Office shifts of a company",
                "description": "`{id, name}` list.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CoreController@Get_office_shift_by_company",
                "x-source": "app/Http/Controllers/hrm/CoreController.php#L28-L33",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "OfficeShift"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Company id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/count_stock": {
            "get": {
                "operationId": "get_api_count_stock",
                "tags": [
                    "Products"
                ],
                "summary": "List stock counts",
                "description": "Paginated history of stock-count exports (`count_stock` table) for the caller's warehouses. Rows: `id, date, warehouse_name, category_name, file_stock` (the generated Excel file name under `/images/count_stock/`). `search` matches warehouse or category name. Also returns the `warehouses` and `categories` lookups.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@count_stock_list",
                "x-source": "app/Http/Controllers/ProductsController.php#L3986-L4051",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "count_stock",
                        "slug": "count_stock",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "CountStock",
                    "Warehouse",
                    "UserWarehouse",
                    "Category"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`stocks[]`, `totalRows`, `warehouses[]`, `categories[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "stocks": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/currencies": {
            "get": {
                "operationId": "get_api_currencies",
                "tags": [
                    "Currencies"
                ],
                "summary": "List currencies",
                "description": "Paginated currencies (`id, name, code, symbol, exchange_rate`) plus `default_currency_id` from settings. `search` matches name or code.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@index",
                "x-source": "app/Http/Controllers/CurrencyController.php#L15-L52",
                "x-route-name": "currencies.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "currency",
                        "policy": "CurrencyPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Currency",
                    "Setting"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`currencies[]`, `totalRows`, `default_currency_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "currencies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "default_currency_id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_currencies",
                "tags": [
                    "Currencies"
                ],
                "summary": "Create a currency",
                "description": "Creates a currency. `exchange_rate` defaults to `1`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@store",
                "x-source": "app/Http/Controllers/CurrencyController.php#L80-L101",
                "x-route-name": "currencies.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "currency",
                        "policy": "CurrencyPolicy"
                    }
                ],
                "x-models": [
                    "Currency"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "ISO code, e.g. `EUR`. Required."
                                    },
                                    "exchange_rate": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-rules": [
                                            "gt:0"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "gt:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Units of this currency per 1 base-currency unit (> 0)."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Currency name. Required."
                                    },
                                    "symbol": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Symbol, e.g. `€`. Required."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name",
                                    "symbol"
                                ]
                            },
                            "example": {
                                "name": "Euro",
                                "code": "EUR",
                                "symbol": "€",
                                "exchange_rate": 0.92
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/currencies/delete/by_selection": {
            "post": {
                "operationId": "post_api_currencies_delete_by_selection",
                "tags": [
                    "Currencies"
                ],
                "summary": "Delete several currencies",
                "description": "Soft-deletes each id in `selectedIds`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@delete_by_selection",
                "x-source": "app/Http/Controllers/CurrencyController.php#L155-L167",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "currency",
                        "policy": "CurrencyPolicy"
                    }
                ],
                "x-models": [
                    "Currency"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of currency ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/currencies/{currency}": {
            "delete": {
                "operationId": "delete_api_currencies_currency",
                "tags": [
                    "Currencies"
                ],
                "summary": "Delete a currency",
                "description": "Soft-deletes the currency.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@destroy",
                "x-source": "app/Http/Controllers/CurrencyController.php#L142-L151",
                "x-route-name": "currencies.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "currency",
                        "policy": "CurrencyPolicy"
                    }
                ],
                "x-models": [
                    "Currency"
                ],
                "parameters": [
                    {
                        "name": "currency",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Currency id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_currencies_currency",
                "tags": [
                    "Currencies"
                ],
                "summary": "(Not implemented) Get a currency",
                "description": "Empty stub; returns an empty `200`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@show",
                "x-source": "app/Http/Controllers/CurrencyController.php#L105-L109",
                "x-route-name": "currencies.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "currency",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Currency id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_currencies_currency",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Currencies"
                ],
                "summary": "Update a currency",
                "description": "Updates name, code, symbol and rate. The default currency's rate is forced to `1`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@update",
                "x-source": "app/Http/Controllers/CurrencyController.php#L113-L138",
                "x-route-name": "currencies.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "currency",
                        "policy": "CurrencyPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Currency"
                ],
                "parameters": [
                    {
                        "name": "currency",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Currency id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code. Required."
                                    },
                                    "exchange_rate": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-rules": [
                                            "gt:0"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "gt:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rate (> 0); ignored for the default currency."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    },
                                    "symbol": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Symbol. Required."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name",
                                    "symbol"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_currencies_currency",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Currencies"
                ],
                "summary": "Update a currency",
                "description": "Updates name, code, symbol and rate. The default currency's rate is forced to `1`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@update",
                "x-source": "app/Http/Controllers/CurrencyController.php#L113-L138",
                "x-route-name": "currencies.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "currency",
                        "policy": "CurrencyPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Currency"
                ],
                "parameters": [
                    {
                        "name": "currency",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Currency id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code. Required."
                                    },
                                    "exchange_rate": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-rules": [
                                            "gt:0"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "gt:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rate (> 0); ignored for the default currency."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    },
                                    "symbol": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Symbol. Required."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name",
                                    "symbol"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/currencies/{id}/set-default": {
            "post": {
                "operationId": "post_api_currencies_id_set_default",
                "tags": [
                    "Currencies"
                ],
                "summary": "Make a currency the default",
                "description": "Sets the currency as the system base currency (settings) and resets its rate to `1`. Other rates are **not** rebased automatically — review them afterwards.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@setDefault",
                "x-source": "app/Http/Controllers/CurrencyController.php#L56-L76",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "currency",
                        "policy": "CurrencyPolicy"
                    }
                ],
                "x-models": [
                    "Currency",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Currency id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `default_currency_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "default_currency_id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/currencies_list": {
            "get": {
                "operationId": "get_api_currencies_list",
                "tags": [
                    "Currencies"
                ],
                "summary": "List currencies for pickers",
                "description": "All currencies (`id, name, code, symbol, exchange_rate`), the `default_currency_id` and whether multi-currency is `enabled`. Requires authentication only.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CurrencyController@Get_Currencies",
                "x-source": "app/Http/Controllers/CurrencyController.php#L171-L183",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Currency",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`currencies[]`, `default_currency_id`, `enabled`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "currencies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "default_currency_id": {},
                                        "enabled": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/custom-field-values": {
            "get": {
                "operationId": "get_api_custom_field_values",
                "tags": [
                    "Custom Fields"
                ],
                "summary": "Get custom field values for a record",
                "description": "Values stored for one customer or supplier, each with its field definition.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@getValues",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L144-L177",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "CustomFieldValue"
                ],
                "parameters": [
                    {
                        "name": "entity_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer or supplier ID."
                    },
                    {
                        "name": "entity_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Fully-qualified model class: `App\\Models\\Client` or `App\\Models\\Provider`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, values: [{custom_field_id, value, custom_field: {...}}]}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "values": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "description": "Missing `entity_type` or `entity_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "entity_type and entity_id are required"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_custom_field_values",
                "tags": [
                    "Custom Fields"
                ],
                "summary": "Save custom field values for a record",
                "description": "Upserts values keyed by custom field ID. Fields that are required and missing/empty cause a 422; unknown field IDs are ignored.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@saveValues",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L183-L238",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "CustomField",
                    "CustomFieldValue"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entity_id": {
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer or supplier ID."
                                    },
                                    "entity_type": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`App\\Models\\Client` or `App\\Models\\Provider`."
                                    },
                                    "values": {
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Object mapping custom field ID → value.",
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "entity_id",
                                    "entity_type",
                                    "values"
                                ]
                            },
                            "example": {
                                "entity_type": "App\\Models\\Client",
                                "entity_id": 12,
                                "values": {
                                    "3": "Gold",
                                    "4": "2026-01-15"
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/custom-fields": {
            "get": {
                "operationId": "get_api_custom_fields",
                "tags": [
                    "Custom Fields"
                ],
                "summary": "List custom field definitions",
                "description": "Active (non-deleted) custom field definitions ordered by ID, optionally filtered to one entity type.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@index",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L16-L32",
                "x-route-name": "custom-fields.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "CustomField"
                ],
                "parameters": [
                    {
                        "name": "entity_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "client",
                                "provider"
                            ]
                        },
                        "description": "Entity type filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{custom_fields: [{id, name, field_type, entity_type, is_required, is_active, default_value}]}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "custom_fields": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_custom_fields",
                "tags": [
                    "Custom Fields"
                ],
                "summary": "Create a custom field",
                "description": "Defines a new field. For `select` fields, `default_value` must be a JSON-encoded array of option strings; otherwise it is the pre-filled default.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@store",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L38-L73",
                "x-route-name": "custom-fields.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "CustomField"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "default_value": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default value, or JSON array of options for `select`."
                                    },
                                    "entity_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "client",
                                            "provider"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:client,provider"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Which form gets the field."
                                    },
                                    "field_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "text",
                                            "number",
                                            "textarea",
                                            "date",
                                            "select",
                                            "checkbox"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:text,number,textarea,date,select,checkbox"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Input type."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Show the field (inactive fields keep their values)."
                                    },
                                    "is_required": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Require a value on save."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label shown on the form."
                                    }
                                },
                                "required": [
                                    "entity_type",
                                    "field_type",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Loyalty tier",
                                "field_type": "select",
                                "entity_type": "client",
                                "is_required": false,
                                "is_active": true,
                                "default_value": "[\"Bronze\",\"Silver\",\"Gold\"]"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, custom_field}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "custom_field": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/custom-fields/{custom_field}": {
            "delete": {
                "operationId": "delete_api_custom_fields_custom_field",
                "tags": [
                    "Custom Fields"
                ],
                "summary": "Delete a custom field",
                "description": "Soft-deletes the definition; stored values are kept but no longer displayed.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@destroy",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L128-L138",
                "x-route-name": "custom-fields.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "CustomField"
                ],
                "parameters": [
                    {
                        "name": "custom_field",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Custom field ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_custom_fields_custom_field",
                "tags": [
                    "Custom Fields"
                ],
                "summary": "Get a custom field",
                "description": "Display the specified custom field GET /custom-fields/{id} /",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@show",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L79-L86",
                "x-route-name": "custom-fields.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "CustomField"
                ],
                "parameters": [
                    {
                        "name": "custom_field",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Custom field ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{custom_field}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "custom_field": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_custom_fields_custom_field",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Custom Fields"
                ],
                "summary": "Update a custom field",
                "description": "Partial update; same validation as create.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@update",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L92-L122",
                "x-route-name": "custom-fields.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "CustomField"
                ],
                "parameters": [
                    {
                        "name": "custom_field",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Custom field ID."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "default_value": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default value, or JSON array of options for `select`."
                                    },
                                    "entity_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "client",
                                            "provider"
                                        ],
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "in:client,provider"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Which form gets the field."
                                    },
                                    "field_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "text",
                                            "number",
                                            "textarea",
                                            "date",
                                            "select",
                                            "checkbox"
                                        ],
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "in:text,number,textarea,date,select,checkbox"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Input type."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show the field (inactive fields keep their values)."
                                    },
                                    "is_required": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Require a value on save."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label shown on the form."
                                    }
                                },
                                "required": [
                                    "entity_type",
                                    "field_type",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Loyalty tier",
                                "field_type": "select",
                                "entity_type": "client",
                                "is_required": false,
                                "is_active": true,
                                "default_value": "[\"Bronze\",\"Silver\",\"Gold\"]"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, custom_field}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "custom_field": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_custom_fields_custom_field",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Custom Fields"
                ],
                "summary": "Update a custom field",
                "description": "Partial update; same validation as create.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "CustomFieldController@update",
                "x-source": "app/Http/Controllers/CustomFieldController.php#L92-L122",
                "x-route-name": "custom-fields.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "CustomField"
                ],
                "parameters": [
                    {
                        "name": "custom_field",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Custom field ID."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "default_value": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default value, or JSON array of options for `select`."
                                    },
                                    "entity_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "client",
                                            "provider"
                                        ],
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "in:client,provider"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Which form gets the field."
                                    },
                                    "field_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "text",
                                            "number",
                                            "textarea",
                                            "date",
                                            "select",
                                            "checkbox"
                                        ],
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "in:text,number,textarea,date,select,checkbox"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Input type."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show the field (inactive fields keep their values)."
                                    },
                                    "is_required": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Require a value on save."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label shown on the form."
                                    }
                                },
                                "required": [
                                    "entity_type",
                                    "field_type",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Loyalty tier",
                                "field_type": "select",
                                "entity_type": "client",
                                "is_required": false,
                                "is_active": true,
                                "default_value": "[\"Bronze\",\"Silver\",\"Gold\"]"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, custom_field}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "custom_field": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/customer-display/generate": {
            "post": {
                "operationId": "post_api_customer_display_generate",
                "tags": [
                    "Customer Display"
                ],
                "summary": "Generate a customer-display access token",
                "description": "Creates a random token valid for 24 hours and returns the public display `url` (`/customer-display?token=…`) and, when the QR library is installed, an SVG `qr` code to scan with the display device. Requires `customer_display_screen_setup`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "Api\\CustomerDisplayController@generate",
                "x-source": "app/Http/Controllers/Api/CustomerDisplayController.php#L19-L40",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "customer_display_screen_setup",
                        "slug": "customer_display_screen_setup",
                        "policy": "SalePolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`token`, `url`, `qr`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "token": {
                                            "type": "string"
                                        },
                                        "url": {
                                            "type": "string"
                                        },
                                        "qr": {}
                                    }
                                },
                                "example": {
                                    "token": "kq8…40 chars…",
                                    "url": "https://shop.example.com/customer-display?token=kq8…",
                                    "qr": "<svg …>"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/customers/import": {
            "post": {
                "operationId": "post_api_customers_import",
                "tags": [
                    "Customers"
                ],
                "summary": "Import customers from Excel",
                "description": "Bulk-creates customers from an `.xls`/`.xlsx` file (max 20 MB). The first row may be a header; recognised columns (case-insensitive, spaces/underscores ignored) are `name`, `firstname`, `lastname`, `code`, `email`, `phone`, `adresse`/`address`, `country`, `city`, `state`, `zip`, `tax_number`, `opening_balance`, `credit_limit`.\n\nEvery row is validated before anything is written: `name` is required, `code` and `email` must be unique within the file and against existing customers. If any row fails, nothing is imported and the response lists the errors with line numbers (`422`). When `code` is omitted the next sequential code is assigned.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@import",
                "x-source": "app/Http/Controllers/ClientController.php#L433-L645",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "customers_import",
                        "slug": "customers_import",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Client",
                    "EcommerceClient"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "customers": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:xls,xlsx",
                                        "maxLength": 20480,
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "mimes:xls,xlsx",
                                            "max:20480"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "The spreadsheet file (`multipart/form-data`)."
                                    }
                                },
                                "required": [
                                    "customers"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`imported` = number of customers created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "imported": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "status": true,
                                    "imported": 25
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/customers/{id}/adjust-opening-balance": {
            "post": {
                "operationId": "post_api_customers_id_adjust_opening_balance",
                "tags": [
                    "Customers"
                ],
                "summary": "Adjust a customer's opening balance",
                "description": "Changes the `opening_balance` of a customer without creating a payment. `mode` controls how `amount` is applied: `add` increases the balance by `|amount|`, `subtract` decreases it by `|amount|`, `set` replaces it. The result is rounded to 2 decimals.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@adjustOpeningBalance",
                "x-source": "app/Http/Controllers/ClientController.php#L891-L925",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount to apply. Sign is ignored for `add`/`subtract`."
                                    },
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "add",
                                            "subtract",
                                            "set"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:add,subtract,set"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`add`, `subtract` or `set`."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "mode"
                                ]
                            },
                            "example": {
                                "mode": "add",
                                "amount": 150
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Previous and new opening balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "previous_opening_balance": {
                                            "type": "number"
                                        },
                                        "opening_balance": {
                                            "type": "number"
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "previous_opening_balance": 200,
                                    "opening_balance": 350
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/customers/{id}/update-points": {
            "post": {
                "operationId": "post_api_customers_id_update_points",
                "tags": [
                    "Customers"
                ],
                "summary": "Set a customer's loyalty points",
                "description": "Overwrites the loyalty `points` balance with the submitted value (no transaction history is written). Requires only `Customers_view`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@updatePoints",
                "x-source": "app/Http/Controllers/ClientController.php#L876-L889",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "points": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New points balance (number)."
                                    }
                                },
                                "required": [
                                    "points"
                                ]
                            },
                            "example": {
                                "points": 250
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/damage_pdf/{id}": {
            "get": {
                "operationId": "get_api_damage_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Damage note PDF",
                "description": "Streams the damage note as a PDF with the damaged lines, quantities and reason. Public route (no token).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "DamageController@damage_pdf",
                "x-source": "app/Http/Controllers/DamageController.php#L721-L772",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Damage",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Damage record ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/damages": {
            "get": {
                "operationId": "get_api_damages",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "List stock damages",
                "description": "Paginated damage documents scoped to the caller's warehouses and record view. Rows: `id, date, Ref, warehouse_name, items`. Also returns `warehouses`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@index",
                "x-source": "app/Http/Controllers/DamageController.php#L27-L106",
                "x-route-name": "damages.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "damage_view",
                        "policy": "DamagePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "warehouse_id",
                    "date"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Damage",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on date (exact)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`damages[]`, `totalRows`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "damages": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_damages",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Create a stock damage",
                "description": "Creates the document and subtracts each line's quantity from the warehouse stock (floored at 0). Combo products subtract component stock. Batch-tracked lines may carry `batches[]` allocations.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@store",
                "x-source": "app/Http/Controllers/DamageController.php#L109-L224",
                "x-route-name": "damages.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "damage_view",
                        "policy": "DamagePolicy"
                    }
                ],
                "x-models": [
                    "Damage",
                    "DamageDetail",
                    "product_warehouse",
                    "Product",
                    "CombinedProduct"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document date."
                                    },
                                    "details": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Lines: `{product_id, product_variant_id, quantity, batches?}`. Required.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason / free text."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse. Required."
                                    }
                                },
                                "required": [
                                    "details",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "warehouse_id": 1,
                                "date": "2026-09-06",
                                "notes": "Water damage",
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 2
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/damages/create": {
            "get": {
                "operationId": "get_api_damages_create",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Get lookups for the damage form",
                "description": "Returns the caller's `warehouses`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@create",
                "x-source": "app/Http/Controllers/DamageController.php#L542-L555",
                "x-route-name": "damages.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "damage_view",
                        "policy": "DamagePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/damages/delete/by_selection": {
            "post": {
                "operationId": "post_api_damages_delete_by_selection",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Delete several damages",
                "description": "Deletes each damage in `selectedIds` with stock restoration.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@delete_by_selection",
                "x-source": "app/Http/Controllers/DamageController.php#L775-L784",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "adjustment_delete",
                        "policy": "DamagePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of damage ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/damages/detail/{id}": {
            "get": {
                "operationId": "get_api_damages_detail_id",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Get damage details",
                "description": "Read-only view: `damage` header (`Ref, date, note, warehouse`) and `details[]` (`code, name, quantity, unit, type (always sub), is_batch_tracked, batches[]`).",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@Damage_detail",
                "x-source": "app/Http/Controllers/DamageController.php#L662-L718",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "damage_view",
                        "policy": "DamagePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Damage",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Damage id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`damage` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "damage": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/damages/{damage}": {
            "delete": {
                "operationId": "delete_api_damages_damage",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Delete a stock damage",
                "description": "Adds the damaged quantities back to stock (and batches) and soft-deletes the document.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@destroy",
                "x-source": "app/Http/Controllers/DamageController.php#L448-L539",
                "x-route-name": "damages.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "adjustment_delete",
                        "policy": "DamagePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Damage",
                    "DamageDetail",
                    "product_warehouse",
                    "Product",
                    "CombinedProduct"
                ],
                "parameters": [
                    {
                        "name": "damage",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Damage id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_damages_damage",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "(Not implemented) Get a damage",
                "description": "Resource stub with an empty body. Use `GET /api/damages/detail/{id}`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@show",
                "x-source": "app/Http/Controllers/DamageController.php#L226-L229",
                "x-route-name": "damages.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "damage",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Damage id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_damages_damage",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Update a stock damage",
                "description": "Restores the stock subtracted by the old lines, then subtracts the new lines. Lines matched by detail `id`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@update",
                "x-source": "app/Http/Controllers/DamageController.php#L232-L445",
                "x-route-name": "damages.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "adjustment_edit",
                        "policy": "DamagePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Damage",
                    "DamageDetail",
                    "product_warehouse",
                    "Product",
                    "CombinedProduct"
                ],
                "parameters": [
                    {
                        "name": "damage",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Damage id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse. Required."
                                    }
                                },
                                "required": [
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_damages_damage",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Update a stock damage",
                "description": "Restores the stock subtracted by the old lines, then subtracts the new lines. Lines matched by detail `id`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@update",
                "x-source": "app/Http/Controllers/DamageController.php#L232-L445",
                "x-route-name": "damages.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "adjustment_edit",
                        "policy": "DamagePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Damage",
                    "DamageDetail",
                    "product_warehouse",
                    "Product",
                    "CombinedProduct"
                ],
                "parameters": [
                    {
                        "name": "damage",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Damage id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse. Required."
                                    }
                                },
                                "required": [
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/damages/{damage}/edit": {
            "get": {
                "operationId": "get_api_damages_damage_edit",
                "tags": [
                    "Stock Damages"
                ],
                "summary": "Get a damage for editing",
                "description": "Form-shaped payload: `damage` (`warehouse_id, notes, date`), `details[]` (`id, detail_id, product_id, product_variant_id, code, name, quantity, current, type, unit, del, product_type, batches`) and `warehouses`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "DamageController@edit",
                "x-source": "app/Http/Controllers/DamageController.php#L558-L659",
                "x-route-name": "damages.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "adjustment_edit",
                        "policy": "DamagePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Damage",
                    "Warehouse",
                    "product_warehouse",
                    "ProductVariant",
                    "UserWarehouse"
                ],
                "parameters": [
                    {
                        "name": "damage",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Damage id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`damage`, `details[]`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "damage": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/dashboard_data": {
            "get": {
                "operationId": "get_api_dashboard_data",
                "tags": [
                    "Dashboard"
                ],
                "summary": "Get dashboard data",
                "description": "Everything the main dashboard renders in one call: KPI cards, sales/purchases series, payments sent vs received, top products, stock alerts, last sales, sales by payment method, stock value and the warehouse list for the selector. Dates default to today when omitted; `warehouse_id=0` means all assigned warehouses.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "DashboardController@dashboard_data",
                "x-source": "app/Http/Controllers/DashboardController.php#L33-L89",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (defaults to today)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (defaults to today)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Restrict to one warehouse (`0` = all assigned)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report_dashboard: {today_sales, today_purchases, return_sales, return_purchases, profit, cogs, expenses...}, sales: [], purchases: [], payments: {received, sent}, products: [], product_report, customers: [], last_sales: [], stock_alert, sales_by_payment, stock_value, warehouses: []}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stock_alert": {},
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "last_sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payments": {},
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "product_report": {},
                                        "report_dashboard": {},
                                        "sales_by_payment": {},
                                        "stock_value": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/delete_backup/{name}": {
            "delete": {
                "operationId": "delete_api_delete_backup_name",
                "tags": [
                    "Backups"
                ],
                "summary": "Delete a backup file",
                "description": "Deletes one backup file from `storage/app/public/backup`. `name` is the filename returned by the list. Returns an empty 200 body.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "BackupController@Delete_Backup",
                "x-source": "app/Http/Controllers/BackupController.php#L170-L181",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "backup",
                        "slug": "backup | setting_system",
                        "policy": "UserPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "name",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Backup filename as returned in `date`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/demo_data": {
            "delete": {
                "operationId": "delete_api_demo_data",
                "tags": [
                    "Demo Data"
                ],
                "summary": "Delete all demo data",
                "description": "Removes every tagged demo row (documents first, then entities) inside a transaction. Fails atomically when a demo record is referenced by real data.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "DemoDataController@reset",
                "x-source": "app/Http/Controllers/DemoDataController.php#L145-L194",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, deleted: {sales, purchases, ...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "deleted": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Some demo records are referenced by real data.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Reset failed: some demo records are referenced by real data (e.g. a real sale using a demo product). Remove those references first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/demo_data/generate": {
            "post": {
                "operationId": "post_api_demo_data_generate",
                "tags": [
                    "Demo Data"
                ],
                "summary": "Generate demo data",
                "description": "Creates up to 300 rows of each requested entity with realistic faker data. Documents (sales, purchases, quotations) draw on existing or freshly generated products/customers/suppliers. Every created row is tagged in `demo_records`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "DemoDataController@generate",
                "x-source": "app/Http/Controllers/DemoDataController.php#L72-L141",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "clients": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of customers."
                                    },
                                    "expenses": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of expenses."
                                    },
                                    "products": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of products."
                                    },
                                    "providers": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of suppliers."
                                    },
                                    "purchases": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of purchases."
                                    },
                                    "quotations": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of quotations."
                                    },
                                    "sales": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of sales."
                                    }
                                }
                            },
                            "example": {
                                "products": 50,
                                "clients": 20,
                                "providers": 10,
                                "sales": 100,
                                "purchases": 30
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, created: {products, clients, ...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "created": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "500": {
                        "description": "Generation failed; partial data may remain.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/demo_data/status": {
            "get": {
                "operationId": "get_api_demo_data_status",
                "tags": [
                    "Demo Data"
                ],
                "summary": "Demo data counts",
                "description": "For each entity type, how many rows are demo-generated versus real.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "DemoDataController@status",
                "x-source": "app/Http/Controllers/DemoDataController.php#L49-L68",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{demo: {products, clients, providers, sales, purchases, quotations, expenses}, real: {...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "demo": {},
                                        "real": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/departments": {
            "get": {
                "operationId": "get_api_departments",
                "tags": [
                    "Departments"
                ],
                "summary": "List departments",
                "description": "Paginated departments joined with company name and head employee (`employee_head`). `search` matches the department name. Sort fields should be prefixed (`departments.id`).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@index",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L15-L51",
                "x-route-name": "departments.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Department"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`departments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "departments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_departments",
                "tags": [
                    "Departments"
                ],
                "summary": "Create a department",
                "description": "Creates a department under a company, optionally with a department head.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@store",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L67-L83",
                "x-route-name": "departments.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Department"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Owning company."
                                    },
                                    "department": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department name."
                                    },
                                    "department_head": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee id of the head (optional).",
                                        "type": "integer"
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/departments/create": {
            "get": {
                "operationId": "get_api_departments_create",
                "tags": [
                    "Departments"
                ],
                "summary": "Create-form data for a department",
                "description": "`companies[]` lookup for the form.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@create",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L53-L63",
                "x-route-name": "departments.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/departments/delete/by_selection": {
            "post": {
                "operationId": "post_api_departments_delete_by_selection",
                "tags": [
                    "Departments"
                ],
                "summary": "Delete selected departments",
                "description": "Bulk soft-delete of departments by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L146-L159",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Department"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Department ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/departments/{department}": {
            "delete": {
                "operationId": "delete_api_departments_department",
                "tags": [
                    "Departments"
                ],
                "summary": "Delete a department",
                "description": "Soft-deletes a department. Employees keep their `department_id`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@destroy",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L129-L142",
                "x-route-name": "departments.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Department"
                ],
                "parameters": [
                    {
                        "name": "department",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Department id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_departments_department",
                "tags": [
                    "Departments"
                ],
                "summary": "Get a department (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@show",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L87-L91",
                "x-route-name": "departments.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "department",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Department id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_departments_department",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Departments"
                ],
                "summary": "Update a department",
                "description": "Updates a department with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@update",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L109-L125",
                "x-route-name": "departments.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Department"
                ],
                "parameters": [
                    {
                        "name": "department",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Department id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Owning company."
                                    },
                                    "department_head": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Head employee id or null.",
                                        "type": "integer"
                                    },
                                    "department": {
                                        "type": "string",
                                        "description": "Department name.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_departments_department",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Departments"
                ],
                "summary": "Update a department",
                "description": "Updates a department with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@update",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L109-L125",
                "x-route-name": "departments.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Department"
                ],
                "parameters": [
                    {
                        "name": "department",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Department id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Owning company."
                                    },
                                    "department_head": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Head employee id or null.",
                                        "type": "integer"
                                    },
                                    "department": {
                                        "type": "string",
                                        "description": "Department name.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/departments/{department}/edit": {
            "get": {
                "operationId": "get_api_departments_department_edit",
                "tags": [
                    "Departments"
                ],
                "summary": "Edit-form data for a department",
                "description": "`companies[]` lookup (the department itself is not returned; use the list).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@edit",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L95-L105",
                "x-route-name": "departments.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "department",
                        "policy": "DepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "department",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Department id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/deposits": {
            "get": {
                "operationId": "get_api_deposits",
                "tags": [
                    "Deposits"
                ],
                "summary": "List deposits",
                "description": "Paginated deposits (own deposits only without record view). Rows: `id, date, deposit_ref, account_name, category, amount, description, created_by`. `search` matches ref, date, category title and account name. Also returns `accounts` and `Deposits_category` lookups.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@index",
                "x-source": "app/Http/Controllers/DepositsController.php#L20-L100",
                "x-route-name": "deposits.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "deposit_view",
                        "policy": "DepositPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "deposit_ref",
                    "account_id",
                    "date",
                    "deposit_category_id"
                ],
                "x-models": [
                    "Deposit",
                    "DepositCategory",
                    "Account"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "account_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Account id."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact date."
                    },
                    {
                        "name": "deposit_category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Category id."
                    },
                    {
                        "name": "deposit_ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`deposits[]`, `totalRows`, `accounts[]`, `Deposits_category[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "deposits": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "Deposits_category": {},
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_deposits",
                "tags": [
                    "Deposits"
                ],
                "summary": "Create a deposit",
                "description": "Creates a deposit from the nested `deposit` object and **adds** the amount to the account balance.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@store",
                "x-source": "app/Http/Controllers/DepositsController.php#L104-L136",
                "x-route-name": "deposits.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "deposit_add",
                        "policy": "DepositPolicy"
                    }
                ],
                "x-models": [
                    "Deposit",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "deposit": {
                                        "x-inferred": true,
                                        "type": "object",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Deposit object.",
                                        "properties": {
                                            "amount": {
                                                "x-inferred": true,
                                                "type": "number",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount. Required."
                                            },
                                            "category_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Deposit category id. Required."
                                            },
                                            "date": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "format": "date",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Date. Required."
                                            }
                                        },
                                        "required": [
                                            "amount",
                                            "category_id",
                                            "date"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "deposit": {
                                    "date": "2026-09-06",
                                    "category_id": 1,
                                    "account_id": 1,
                                    "amount": 1000,
                                    "description": "Owner capital"
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/deposits/create": {
            "get": {
                "operationId": "get_api_deposits_create",
                "tags": [
                    "Deposits"
                ],
                "summary": "Get lookups for the deposit form",
                "description": "`deposits_category` (`id, title`) and `accounts` (`id, account_name`).",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@create",
                "x-source": "app/Http/Controllers/DepositsController.php#L295-L307",
                "x-route-name": "deposits.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "deposit_add",
                        "policy": "DepositPolicy"
                    }
                ],
                "x-models": [
                    "DepositCategory",
                    "Account"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "deposits_category": {},
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/deposits/{deposit}": {
            "delete": {
                "operationId": "delete_api_deposits_deposit",
                "tags": [
                    "Deposits"
                ],
                "summary": "Delete a deposit",
                "description": "Soft-deletes the deposit and subtracts its amount from the account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@destroy",
                "x-source": "app/Http/Controllers/DepositsController.php#L202-L232",
                "x-route-name": "deposits.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "deposit_delete",
                        "policy": "DepositPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Deposit",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "deposit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Deposit id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_deposits_deposit",
                "tags": [
                    "Deposits"
                ],
                "summary": "(Not implemented) Get a deposit",
                "description": "Empty stub; returns an empty `200`. Use the edit endpoint.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@show",
                "x-source": "app/Http/Controllers/DepositsController.php#L140-L144",
                "x-route-name": "deposits.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "deposit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Deposit id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_deposits_deposit",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Deposits"
                ],
                "summary": "Update a deposit",
                "description": "Removes the old amount from the old account, saves the new values and adds the new amount to the (possibly different) account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@update",
                "x-source": "app/Http/Controllers/DepositsController.php#L148-L198",
                "x-route-name": "deposits.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "deposit_edit",
                        "policy": "DepositPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Deposit",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "deposit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Deposit fields as a nested object: `date` (YYYY-MM-DD), `account_id`, `category_id` (deposit category), `amount`, `description`. Changing the account or amount adjusts both account balances."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "deposit": {
                                        "properties": {
                                            "amount": {
                                                "x-inferred": true,
                                                "type": "number",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount deposited."
                                            },
                                            "category_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Deposit category ID."
                                            },
                                            "date": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "format": "date",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Deposit date."
                                            }
                                        },
                                        "required": [
                                            "amount",
                                            "category_id",
                                            "date"
                                        ],
                                        "description": "Deposit fields as a nested object: `date` (YYYY-MM-DD), `account_id`, `category_id` (deposit category), `amount`, `description`. Changing the account or amount adjusts both account balances.",
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_deposits_deposit",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Deposits"
                ],
                "summary": "Update a deposit",
                "description": "Removes the old amount from the old account, saves the new values and adds the new amount to the (possibly different) account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@update",
                "x-source": "app/Http/Controllers/DepositsController.php#L148-L198",
                "x-route-name": "deposits.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "deposit_edit",
                        "policy": "DepositPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Deposit",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "deposit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Deposit fields as a nested object: `date` (YYYY-MM-DD), `account_id`, `category_id` (deposit category), `amount`, `description`. Changing the account or amount adjusts both account balances."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "deposit": {
                                        "properties": {
                                            "amount": {
                                                "x-inferred": true,
                                                "type": "number",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount deposited."
                                            },
                                            "category_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Deposit category ID."
                                            },
                                            "date": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "format": "date",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Deposit date."
                                            }
                                        },
                                        "required": [
                                            "amount",
                                            "category_id",
                                            "date"
                                        ],
                                        "description": "Deposit fields as a nested object: `date` (YYYY-MM-DD), `account_id`, `category_id` (deposit category), `amount`, `description`. Changing the account or amount adjusts both account balances.",
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/deposits/{deposit}/edit": {
            "get": {
                "operationId": "get_api_deposits_deposit_edit",
                "tags": [
                    "Deposits"
                ],
                "summary": "Get a deposit for editing",
                "description": "`deposit` (`account_id, category_id, date, amount, description`) plus the `deposit_category` and `accounts` lookups.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@edit",
                "x-source": "app/Http/Controllers/DepositsController.php#L311-L363",
                "x-route-name": "deposits.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "deposit_edit",
                        "policy": "DepositPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Deposit",
                    "Account",
                    "DepositCategory"
                ],
                "parameters": [
                    {
                        "name": "deposit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Deposit id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`deposit`, `deposit_category[]`, `accounts[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "deposit": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "deposit_category": {},
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/deposits_category": {
            "get": {
                "operationId": "get_api_deposits_category",
                "tags": [
                    "Deposit Categories"
                ],
                "summary": "List deposit categories",
                "description": "Paginated categories; `search` matches the title.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryDepositController@index",
                "x-source": "app/Http/Controllers/CategoryDepositController.php#L13-L47",
                "x-route-name": "deposits_category.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "deposit_view",
                        "policy": "DepositCategoryPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "DepositCategory"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`deposits_category[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "deposits_category": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_deposits_category",
                "tags": [
                    "Deposit Categories"
                ],
                "summary": "Create a deposit category",
                "description": "Creates a category.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryDepositController@store",
                "x-source": "app/Http/Controllers/CategoryDepositController.php#L51-L64",
                "x-route-name": "deposits_category.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "deposit_add",
                        "policy": "DepositCategoryPolicy"
                    }
                ],
                "x-models": [
                    "DepositCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Category title. Required."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/deposits_category/{deposits_category}": {
            "delete": {
                "operationId": "delete_api_deposits_category_deposits_category",
                "tags": [
                    "Deposit Categories"
                ],
                "summary": "Delete a deposit category",
                "description": "Soft-deletes the category.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryDepositController@destroy",
                "x-source": "app/Http/Controllers/CategoryDepositController.php#L95-L105",
                "x-route-name": "deposits_category.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "deposit_delete",
                        "policy": "DepositCategoryPolicy"
                    }
                ],
                "x-models": [
                    "DepositCategory"
                ],
                "parameters": [
                    {
                        "name": "deposits_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_deposits_category_deposits_category",
                "tags": [
                    "Deposit Categories"
                ],
                "summary": "(Not implemented) Get a deposit category",
                "description": "Empty stub; returns an empty `200`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryDepositController@show",
                "x-source": "app/Http/Controllers/CategoryDepositController.php#L68-L72",
                "x-route-name": "deposits_category.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "deposits_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_deposits_category_deposits_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Deposit Categories"
                ],
                "summary": "Update a deposit category",
                "description": "Renames the category.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryDepositController@update",
                "x-source": "app/Http/Controllers/CategoryDepositController.php#L76-L91",
                "x-route-name": "deposits_category.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "deposit_edit",
                        "policy": "DepositCategoryPolicy"
                    }
                ],
                "x-models": [
                    "DepositCategory"
                ],
                "parameters": [
                    {
                        "name": "deposits_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title. Required."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_deposits_category_deposits_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Deposit Categories"
                ],
                "summary": "Update a deposit category",
                "description": "Renames the category.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryDepositController@update",
                "x-source": "app/Http/Controllers/CategoryDepositController.php#L76-L91",
                "x-route-name": "deposits_category.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "deposit_edit",
                        "policy": "DepositCategoryPolicy"
                    }
                ],
                "x-models": [
                    "DepositCategory"
                ],
                "parameters": [
                    {
                        "name": "deposits_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title. Required."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/deposits_category_delete_by_selection": {
            "post": {
                "operationId": "post_api_deposits_category_delete_by_selection",
                "tags": [
                    "Deposit Categories"
                ],
                "summary": "Delete several deposit categories",
                "description": "Soft-deletes each id in `selectedIds`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryDepositController@delete_by_selection",
                "x-source": "app/Http/Controllers/CategoryDepositController.php#L109-L123",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "deposit_delete",
                        "policy": "DepositCategoryPolicy"
                    }
                ],
                "x-models": [
                    "DepositCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of category ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/deposits_delete_by_selection": {
            "post": {
                "operationId": "post_api_deposits_delete_by_selection",
                "tags": [
                    "Deposits"
                ],
                "summary": "Delete several deposits",
                "description": "Soft-deletes each deposit in `selectedIds`, re-balancing the accounts.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "DepositsController@delete_by_selection",
                "x-source": "app/Http/Controllers/DepositsController.php#L236-L271",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "deposit_delete",
                        "policy": "DepositPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Deposit",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of deposit ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/designations": {
            "get": {
                "operationId": "get_api_designations",
                "tags": [
                    "Designations"
                ],
                "summary": "List designations",
                "description": "Paginated designations mapped to `id, designation, company_name, company_id, department_name, department_id`. `search` matches the designation title.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@index",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L15-L60",
                "x-route-name": "designations.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Designation"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`designations[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "designations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_designations",
                "tags": [
                    "Designations"
                ],
                "summary": "Create a designation",
                "description": "Creates a job designation (title) under a department.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@store",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L76-L93",
                "x-route-name": "designations.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-models": [
                    "Designation"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "department": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department **id** (despite the name).",
                                        "type": "integer"
                                    },
                                    "designation": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department",
                                    "designation"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/designations/create": {
            "get": {
                "operationId": "get_api_designations_create",
                "tags": [
                    "Designations"
                ],
                "summary": "Create-form data for a designation",
                "description": "Lookup data for the designation form: companies and departments.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@create",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L62-L72",
                "x-route-name": "designations.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/designations/delete/by_selection": {
            "post": {
                "operationId": "post_api_designations_delete_by_selection",
                "tags": [
                    "Designations"
                ],
                "summary": "Delete selected designations",
                "description": "Bulk soft-delete of designations by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L157-L170",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-models": [
                    "Designation"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Designation ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/designations/{designation}": {
            "delete": {
                "operationId": "delete_api_designations_designation",
                "tags": [
                    "Designations"
                ],
                "summary": "Delete a designation",
                "description": "Soft-deletes a designation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@destroy",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L140-L153",
                "x-route-name": "designations.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-models": [
                    "Designation"
                ],
                "parameters": [
                    {
                        "name": "designation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Designation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_designations_designation",
                "tags": [
                    "Designations"
                ],
                "summary": "Get a designation (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@show",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L97-L101",
                "x-route-name": "designations.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "designation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Designation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_designations_designation",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Designations"
                ],
                "summary": "Update a designation",
                "description": "Updates a designation with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@update",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L119-L136",
                "x-route-name": "designations.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-models": [
                    "Designation"
                ],
                "parameters": [
                    {
                        "name": "designation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Designation id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "department": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department id.",
                                        "type": "integer"
                                    },
                                    "designation": {
                                        "type": "string",
                                        "description": "Title.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department",
                                    "designation"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_designations_designation",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Designations"
                ],
                "summary": "Update a designation",
                "description": "Updates a designation with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@update",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L119-L136",
                "x-route-name": "designations.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-models": [
                    "Designation"
                ],
                "parameters": [
                    {
                        "name": "designation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Designation id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "department": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department id.",
                                        "type": "integer"
                                    },
                                    "designation": {
                                        "type": "string",
                                        "description": "Title.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department",
                                    "designation"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/designations/{designation}/edit": {
            "get": {
                "operationId": "get_api_designations_designation_edit",
                "tags": [
                    "Designations"
                ],
                "summary": "Edit-form data for a designation",
                "description": "The designation with the lookups needed by the edit form.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@edit",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L105-L115",
                "x-route-name": "designations.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "designation",
                        "policy": "DesignationPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "designation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Designation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/direct_network_print/{id}": {
            "post": {
                "operationId": "post_api_direct_network_print_id",
                "tags": [
                    "Sales"
                ],
                "summary": "Print a receipt on a network printer",
                "description": "**Public** (no authentication). Renders the sale receipt as ESC/POS bytes (58 mm or 80 mm width per POS settings) and sends it over TCP to the network printer configured in POS settings. Returns the number of `bytes` written and the `printer` address.",
                "x-section": "Sales",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "SalesController@Direct_Network_Print_POS",
                "x-source": "app/Http/Controllers/SalesController.php#L1832-L1974",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "PosSetting",
                    "Sale",
                    "Setting",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success`, `bytes`, `printer`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "bytes": {},
                                        "printer": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Direct network printing disabled or printer IP/port missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Network printer IP or port is not configured."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "Connection or write failure.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Printer connection established but write failed."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/documents": {
            "get": {
                "operationId": "get_api_documents",
                "tags": [
                    "Document Archive"
                ],
                "summary": "List documents",
                "description": "Paginated (default 12, newest first; sortable `id, title, file_name, size, extension, expiry_date, created_at, updated_at`) documents with folder, uploader name, `url`, `size_label`, `tags[]`, `is_expired` / `expires_in_days`. `search` matches title, file name, reference or tags.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@index",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L50-L77",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "documents_view",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Document"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Created to."
                    },
                    {
                        "name": "expiring",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Days ahead: only documents expiring within N days (default 30 when set)."
                    },
                    {
                        "name": "folder_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Folder filter (`0` / `null` for uncategorised)."
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "File kind: `image`, `pdf`, `word`, `excel`, `powerpoint`, `archive`, `video`, `audio`, `text`, `other`."
                    },
                    {
                        "name": "starred",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = starred only."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Created from."
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Exact tag."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`documents[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_documents",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Upload documents",
                "description": "Multipart. Each file in `files[]` (max 50 MB each) becomes its own document (version 1). `title` applies only to a single-file upload; otherwise the file name is used.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@store",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L174-L228",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "documents_add",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document",
                    "DocumentVersion"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "expiry_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Expiry date."
                                    },
                                    "files": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "maxLength": 51200,
                                            "x-laravel-rules": [
                                                "required",
                                                "file",
                                                "max:51200"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "One or more files."
                                    },
                                    "folder_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "document_folders,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:document_folders,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target folder."
                                    },
                                    "is_starred": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Star flag."
                                    },
                                    "reference": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Reference code (max 100)."
                                    },
                                    "tags": {
                                        "x-inferred": true,
                                        "type": "array",
                                        "items": {},
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tags (array or comma-separated string)."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (single upload)."
                                    }
                                },
                                "required": [
                                    "files"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success`, created `ids[]`, `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "ids": {},
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/delete/by_selection": {
            "post": {
                "operationId": "post_api_documents_delete_by_selection",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Delete selected documents",
                "description": "Bulk delete of archive documents by `selectedIds`; files and versions are removed.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@deleteBySelection",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L270-L278",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "documents_delete",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/folders": {
            "get": {
                "operationId": "get_api_documents_folders",
                "tags": [
                    "Document Archive"
                ],
                "summary": "List folders",
                "description": "Flat list (`id, name, parent_id, description, color, count`) — the client builds the tree — plus the `uncategorised` count.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@folders",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L415-L439",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "documents_view",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "DocumentFolder",
                    "Document"
                ],
                "responses": {
                    "200": {
                        "description": "`folders[]` and `uncategorised`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "folders": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "uncategorised": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_documents_folders",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Create a folder",
                "description": "Creates a folder (`name`, optional `parent_id`) in the document archive.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@storeFolder",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L441-L459",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "documents_add",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "DocumentFolder"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "color": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hex colour for the UI."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (max 191)."
                                    },
                                    "parent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "document_folders,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:document_folders,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Parent folder."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/folders/{id}": {
            "delete": {
                "operationId": "delete_api_documents_folders_id",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Delete a folder",
                "description": "Its documents and sub-folders are detached to the root, not deleted.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@destroyFolder",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L492-L503",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "documents_delete",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "DocumentFolder",
                    "Document"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Folder id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_documents_folders_id",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Update a folder",
                "description": "A folder cannot be moved inside itself or one of its descendants (`422`).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@updateFolder",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L461-L486",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "documents_edit",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "DocumentFolder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Folder id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "color": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Colour."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "parent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "document_folders,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:document_folders,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Parent."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/move/by_selection": {
            "post": {
                "operationId": "post_api_documents_move_by_selection",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Move documents to a folder",
                "description": "Bulk file-away: move a selection into a folder (null = uncategorised).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@moveBySelection",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L281-L294",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "documents_edit",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "folder_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "document_folders,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:document_folders,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target folder, or null for uncategorised."
                                    },
                                    "selectedIds": {
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Document ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "required": [
                                    "selectedIds"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/stats": {
            "get": {
                "operationId": "get_api_documents_stats",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Archive statistics",
                "description": "`total`, `storage` bytes + `storage_label`, `starred`, `folders`, `expiring_soon` (30 days), `expired`, `added_this_month`, and all `tags`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@stats",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L510-L534",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "documents_view",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document",
                    "DocumentFolder"
                ],
                "responses": {
                    "200": {
                        "description": "Stats object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "storage": {},
                                        "storage_label": {},
                                        "starred": {
                                            "type": "integer"
                                        },
                                        "folders": {
                                            "type": "integer"
                                        },
                                        "expiring_soon": {
                                            "type": "integer"
                                        },
                                        "expired": {
                                            "type": "integer"
                                        },
                                        "added_this_month": {
                                            "type": "integer"
                                        },
                                        "tags": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/{id}": {
            "delete": {
                "operationId": "delete_api_documents_id",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Delete a document",
                "description": "Soft delete; files stay on disk.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@destroy",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L261-L268",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "documents_delete",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_documents_id",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Get a document",
                "description": "Document metadata plus its `versions[]` (`version, file_name, url, size, note, uploaded_by_name, created_at`).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@show",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L145-L168",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "documents_view",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`document`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "document": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_documents_id",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Update document metadata",
                "description": "Title, folder, tags, reference, expiry and description. To replace the file, upload a new version.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@update",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L231-L255",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "documents_edit",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "expiry_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Expiry."
                                    },
                                    "folder_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "document_folders,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:document_folders,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Folder."
                                    },
                                    "reference": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Reference."
                                    },
                                    "tags": {
                                        "x-inferred": true,
                                        "type": "array",
                                        "items": {},
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tags."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/{id}/download": {
            "get": {
                "operationId": "get_api_documents_id_download",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Download a document",
                "description": "Sends the current file under its original name.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@download",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L316-L328",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "documents_view",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/{id}/star": {
            "post": {
                "operationId": "post_api_documents_id_star",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Toggle star",
                "description": "Toggles the star/favourite flag of a document for the current user. Returns the new state.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@toggleStar",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L296-L305",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "documents_edit",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and new `is_starred`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "is_starred": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/{id}/versions": {
            "post": {
                "operationId": "post_api_documents_id_versions",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Upload a new version",
                "description": "Replaces the current file and appends a version entry; previous versions stay downloadable.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@storeVersion",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L335-L358",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "documents_edit",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document",
                    "DocumentVersion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "maxLength": 51200,
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "max:51200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "New file (max 50 MB)."
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Version note (max 255)."
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and new `version` number.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "version": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/{id}/versions/{versionId}/download": {
            "get": {
                "operationId": "get_api_documents_id_versions_versionId_download",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Download a specific version",
                "description": "Downloads a specific historical version of the document.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@downloadVersion",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L360-L372",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "documents_view",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "DocumentVersion"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    },
                    {
                        "name": "versionId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Version id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/documents/{id}/versions/{versionId}/restore": {
            "post": {
                "operationId": "post_api_documents_id_versions_versionId_restore",
                "tags": [
                    "Document Archive"
                ],
                "summary": "Restore an older version",
                "description": "Creates a **new** version pointing at the old file (history is append-only) and makes it current.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "DocumentArchiveController@restoreVersion",
                "x-source": "app/Http/Controllers/DocumentArchiveController.php#L378-L408",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "documents_edit",
                        "policy": "DocumentPolicy"
                    }
                ],
                "x-models": [
                    "Document",
                    "DocumentVersion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    },
                    {
                        "name": "versionId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Version id to restore."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and new `version`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "version": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/ecommerce_clients": {
            "get": {
                "operationId": "get_api_ecommerce_clients",
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "List store accounts",
                "description": "Paginated list of online-store accounts joined with their customer. Rows: `id, client_id, client_code, client_name, phone, email, username, status (1/0), is_blocked, email_verified`. `search` matches account email/username and the customer's name, code or phone.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@accounts",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L87-L143",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "EcommerceClient"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`accounts[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "accounts": [
                                        {
                                            "id": 5,
                                            "client_id": 3,
                                            "client_code": 3,
                                            "client_name": "ACME Ltd",
                                            "phone": "+212600000000",
                                            "email": "jane@acme.test",
                                            "username": "ACME Ltd",
                                            "status": 1,
                                            "is_blocked": false,
                                            "email_verified": true
                                        }
                                    ],
                                    "totalRows": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/ecommerce_clients/{id}": {
            "delete": {
                "operationId": "delete_api_ecommerce_clients_id",
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "Delete a store account",
                "description": "Soft-deletes the online-store account only; the customer record stays intact and can get a new account later.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@destroyAccount",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L204-L214",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Customers_delete",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store-account id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_ecommerce_clients_id",
                "tags": [
                    "Customer Store Accounts"
                ],
                "summary": "Update a store account",
                "description": "Updates a store account by its own id. `email` is required and is also copied to the linked customer. `password` is only changed when present and non-empty. `status` (active) and `is_blocked` are applied only when the key is present in the payload.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientsEcommerceController@updateAccount",
                "x-source": "app/Http/Controllers/ClientsEcommerceController.php#L147-L200",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Customers_edit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient",
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store-account id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "ecommerce_clients,email ->ignore->whereNull",
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:clients,email ->ignore->whereNull",
                                            "unique:ecommerce_clients,email ->ignore->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Login email; unique across customers and store accounts."
                                    },
                                    "is_blocked": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`true` blocks the customer from logging in (e.g. abuse)."
                                    },
                                    "password": {
                                        "type": "string",
                                        "minLength": 6,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "min:6"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New password (min 6). Omit to keep."
                                    },
                                    "status": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`true` = account active, `false` = disabled."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "email": "jane@acme.test",
                                "status": true,
                                "is_blocked": false
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/employee_account": {
            "get": {
                "operationId": "get_api_employee_account",
                "tags": [
                    "Employee Accounts"
                ],
                "summary": "List employee accounts (not implemented)",
                "description": "**Not implemented** — use *Bank accounts of an employee*.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeAccountController@index",
                "x-source": "app/Http/Controllers/hrm/EmployeeAccountController.php#L13-L16",
                "x-route-name": "employee_account.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_employee_account",
                "tags": [
                    "Employee Accounts"
                ],
                "summary": "Create a bank account",
                "description": "Stores `$request->all()`, so `employee_id` must be sent even though it is not validated.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeAccountController@store",
                "x-source": "app/Http/Controllers/hrm/EmployeeAccountController.php#L20-L33",
                "x-route-name": "employee_account.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "add_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "EmployeeAccount"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_no": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account number."
                                    },
                                    "bank_branch": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Branch."
                                    },
                                    "bank_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bank name."
                                    },
                                    "employee_id": {
                                        "type": "integer",
                                        "description": "Owning employee id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "account_no",
                                    "bank_branch",
                                    "bank_name",
                                    "employee_id"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/employee_account/{employee_account}": {
            "delete": {
                "operationId": "delete_api_employee_account_employee_account",
                "tags": [
                    "Employee Accounts"
                ],
                "summary": "Delete a bank account",
                "description": "Deletes an employee bank account.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeAccountController@destroy",
                "x-source": "app/Http/Controllers/hrm/EmployeeAccountController.php#L62-L71",
                "x-route-name": "employee_account.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "delete_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "EmployeeAccount"
                ],
                "parameters": [
                    {
                        "name": "employee_account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_employee_account_employee_account",
                "tags": [
                    "Employee Accounts"
                ],
                "summary": "Get an employee account (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeAccountController@show",
                "x-source": "app/Http/Controllers/hrm/EmployeeAccountController.php#L37-L41",
                "x-route-name": "employee_account.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "employee_account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_employee_account_employee_account",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Employee Accounts"
                ],
                "summary": "Update a bank account",
                "description": "Updates bank name, account holder, account number and branch.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeAccountController@update",
                "x-source": "app/Http/Controllers/hrm/EmployeeAccountController.php#L45-L58",
                "x-route-name": "employee_account.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "EmployeeAccount"
                ],
                "parameters": [
                    {
                        "name": "employee_account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_no": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account number."
                                    },
                                    "bank_branch": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Branch."
                                    },
                                    "bank_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bank name."
                                    },
                                    "employee_id": {
                                        "type": "integer",
                                        "description": "Owning employee id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "account_no",
                                    "bank_branch",
                                    "bank_name"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_employee_account_employee_account",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Employee Accounts"
                ],
                "summary": "Update a bank account",
                "description": "Updates bank name, account holder, account number and branch.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeAccountController@update",
                "x-source": "app/Http/Controllers/hrm/EmployeeAccountController.php#L45-L58",
                "x-route-name": "employee_account.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "EmployeeAccount"
                ],
                "parameters": [
                    {
                        "name": "employee_account",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Account id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_no": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account number."
                                    },
                                    "bank_branch": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Branch."
                                    },
                                    "bank_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bank name."
                                    },
                                    "employee_id": {
                                        "type": "integer",
                                        "description": "Owning employee id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "account_no",
                                    "bank_branch",
                                    "bank_name"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/employees": {
            "get": {
                "operationId": "get_api_employees",
                "tags": [
                    "Employees"
                ],
                "summary": "List employees",
                "description": "Paginated **active** employees (no `leaving_date`) with `firstname, lastname, phone, company_name, department_name, designation_name, office_shift_name`. `search` matches first name, last name or username. Also returns the `companies` lookup.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@index",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L21-L91",
                "x-route-name": "employees.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "view_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "username",
                    "employment_type",
                    "company_id"
                ],
                "x-models": [
                    "Employee",
                    "Company"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "company_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on company."
                    },
                    {
                        "name": "employment_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter (LIKE) on employment type."
                    },
                    {
                        "name": "username",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter (LIKE) on username."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`employees[]`, `companies[]`, `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_employees",
                "tags": [
                    "Employees"
                ],
                "summary": "Create an employee",
                "description": "Creates the basic record; `username` is set to `firstname lastname`. Employment details, salary and leave balance are set later with *Update an employee*.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@store",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L109-L141",
                "x-route-name": "employees.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "add_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "birth_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date of birth."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "designation_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Designation."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Gender (free text, UI uses `male` / `female`)."
                                    },
                                    "joining_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Joining date."
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "office_shift_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Office shift."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department_id",
                                    "designation_id",
                                    "firstname",
                                    "gender",
                                    "lastname",
                                    "office_shift_id"
                                ]
                            },
                            "example": {
                                "firstname": "Sara",
                                "lastname": "Alami",
                                "gender": "female",
                                "email": "sara@stocky.test",
                                "phone": "+212611111111",
                                "country": "Morocco",
                                "birth_date": "1992-04-10",
                                "company_id": 1,
                                "department_id": 2,
                                "designation_id": 5,
                                "office_shift_id": 1,
                                "joining_date": "2026-09-01"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/employees/create": {
            "get": {
                "operationId": "get_api_employees_create",
                "tags": [
                    "Employees"
                ],
                "summary": "Create-form data for an employee",
                "description": "Lookup data for the employee form: companies, departments, designations, office shifts and users. No side effects.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@create",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L95-L105",
                "x-route-name": "employees.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "add_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/employees/delete/by_selection": {
            "post": {
                "operationId": "post_api_employees_delete_by_selection",
                "tags": [
                    "Employees"
                ],
                "summary": "Delete selected employees",
                "description": "Bulk soft-delete of employees by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L269-L283",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "delete_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/employees/{employee}": {
            "delete": {
                "operationId": "delete_api_employees_employee",
                "tags": [
                    "Employees"
                ],
                "summary": "Delete an employee",
                "description": "Soft-deletes the employee.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@destroy",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L256-L265",
                "x-route-name": "employees.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "delete_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "employee",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Employee id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_employees_employee",
                "tags": [
                    "Employees"
                ],
                "summary": "Get an employee",
                "description": "The full `employee` record plus the lookups used by the profile page: `companies`, `office_shifts` and `departments` of the employee's company, `designations` of its department.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@show",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L145-L164",
                "x-route-name": "employees.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "view_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee",
                    "Company",
                    "OfficeShift",
                    "Department",
                    "Designation"
                ],
                "parameters": [
                    {
                        "name": "employee",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Employee id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`employee`, `companies[]`, `office_shifts[]`, `departments[]`, `designations[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "employee": {},
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "office_shifts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "departments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "designations": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_employees_employee",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Employees"
                ],
                "summary": "Update an employee",
                "description": "Full update of the profile. Leave balance rule: when the stored `total_leave` is 0, `remaining_leave` is set to the new `total_leave`; otherwise `remaining_leave` is adjusted by the difference between old and new totals. Setting `leaving_date` removes the employee from the active list.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@update",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L187-L252",
                "x-route-name": "employees.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "employee",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Employee id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "basic_salary": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Monthly basic salary."
                                    },
                                    "birth_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date of birth."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "country": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "designation_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Designation."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "employment_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "e.g. `Full Time`, `Part Time`, `Contract`."
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Gender."
                                    },
                                    "hourly_rate": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Hourly rate."
                                    },
                                    "joining_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Joining date."
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "leaving_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Leaving date (null = active)."
                                    },
                                    "marital_status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Marital status."
                                    },
                                    "office_shift_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Office shift."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "province": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Province / state."
                                    },
                                    "remaining_leave": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Current remaining leave (used by the balance rule).",
                                        "type": "number"
                                    },
                                    "role_users_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Linked user account id (for portal login)."
                                    },
                                    "total_leave": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Annual leave entitlement (days)."
                                    },
                                    "zipcode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "country",
                                    "department_id",
                                    "designation_id",
                                    "firstname",
                                    "gender",
                                    "lastname",
                                    "office_shift_id",
                                    "phone",
                                    "total_leave"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_employees_employee",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Employees"
                ],
                "summary": "Update an employee",
                "description": "Full update of the profile. Leave balance rule: when the stored `total_leave` is 0, `remaining_leave` is set to the new `total_leave`; otherwise `remaining_leave` is adjusted by the difference between old and new totals. Setting `leaving_date` removes the employee from the active list.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@update",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L187-L252",
                "x-route-name": "employees.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "employee",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Employee id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "basic_salary": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Monthly basic salary."
                                    },
                                    "birth_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date of birth."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "country": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "designation_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Designation."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "employment_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "e.g. `Full Time`, `Part Time`, `Contract`."
                                    },
                                    "firstname": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Gender."
                                    },
                                    "hourly_rate": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Hourly rate."
                                    },
                                    "joining_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Joining date."
                                    },
                                    "lastname": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "leaving_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Leaving date (null = active)."
                                    },
                                    "marital_status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Marital status."
                                    },
                                    "office_shift_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Office shift."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "province": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Province / state."
                                    },
                                    "remaining_leave": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Current remaining leave (used by the balance rule).",
                                        "type": "number"
                                    },
                                    "role_users_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Linked user account id (for portal login)."
                                    },
                                    "total_leave": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Annual leave entitlement (days)."
                                    },
                                    "zipcode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "country",
                                    "department_id",
                                    "designation_id",
                                    "firstname",
                                    "gender",
                                    "lastname",
                                    "office_shift_id",
                                    "phone",
                                    "total_leave"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/employees/{employee}/edit": {
            "get": {
                "operationId": "get_api_employees_employee_edit",
                "tags": [
                    "Employees"
                ],
                "summary": "Edit-form data for an employee",
                "description": "Same payload as *Get an employee*.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@edit",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L166-L183",
                "x-route-name": "employees.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee",
                    "Company",
                    "OfficeShift",
                    "Department",
                    "Designation"
                ],
                "parameters": [
                    {
                        "name": "employee",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Employee id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`employee`, `companies[]`, `office_shifts[]`, `departments[]`, `designations[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "employee": {},
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "office_shifts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "departments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "designations": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/error-logs": {
            "get": {
                "operationId": "get_api_error_logs",
                "tags": [
                    "Error Logs"
                ],
                "summary": "List error logs",
                "description": "Paginated error rows with a summary (total, last 24 h, top contexts), a daily time series and per-context counts, all computed over the same filtered scope. Sortable by `SortField`/`SortType`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "ErrorLogController@index",
                "x-source": "app/Http/Controllers/ErrorLogController.php#L11-L111",
                "x-route-name": "error_logs.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "report_error_logs",
                        "policy": "ErrorLogPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ErrorLog"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "context",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Exact context filter (e.g. `pos`, `zatca`, `queue`)."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Start date (inclusive)."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Rows per page (default 10)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string",
                            "format": "date"
                        },
                        "description": "End date (inclusive)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{logs: [{id, context, message, details, created_at}], total, summary, timeseries: [{date, count}], by_context, contexts: []}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "logs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_context": {},
                                        "contexts": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses": {
            "get": {
                "operationId": "get_api_expenses",
                "tags": [
                    "Expenses"
                ],
                "summary": "List expenses",
                "description": "Paginated expenses scoped to the caller's warehouses and record view. Rows: `id, date, Ref, details, amount, warehouse_name, category_name, account_name, payment_method, documents_count, created_by`. `search` matches Ref, date, details, category, warehouse and account names. Also returns the `Expenses_category`, `warehouses`, `accounts` and `payment_methods` lookups.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@index",
                "x-source": "app/Http/Controllers/ExpensesController.php#L24-L147",
                "x-route-name": "expenses.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "expense_view",
                        "policy": "ExpensePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "warehouse_id",
                    "date",
                    "expense_category_id",
                    "account_id",
                    "payment_method_id"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Expense",
                    "ExpenseCategory",
                    "Account",
                    "PaymentMethod",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "account_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Account id."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact date."
                    },
                    {
                        "name": "expense_category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Category id."
                    },
                    {
                        "name": "payment_method_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Payment method id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`expenses[]`, `totalRows`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "expenses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "Expenses_category": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_expenses",
                "tags": [
                    "Expenses"
                ],
                "summary": "Create an expense",
                "description": "Creates an expense from the nested `expense` object with an auto `Ref` and **subtracts** the amount from the account balance.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@store",
                "x-source": "app/Http/Controllers/ExpensesController.php#L151-L188",
                "x-route-name": "expenses.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "expense_add",
                        "policy": "ExpensePolicy"
                    }
                ],
                "x-models": [
                    "Expense",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "expense": {
                                        "x-inferred": true,
                                        "type": "object",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Expense object.",
                                        "properties": {
                                            "amount": {
                                                "x-inferred": true,
                                                "type": "number",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount. Required."
                                            },
                                            "category_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Expense category id. Required."
                                            },
                                            "date": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "format": "date",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Date. Required."
                                            },
                                            "details": {
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Description / details text. Required.",
                                                "type": "string"
                                            },
                                            "payment_method_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Payment method id. Required."
                                            },
                                            "warehouse_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Warehouse the expense belongs to. Required."
                                            }
                                        },
                                        "required": [
                                            "amount",
                                            "category_id",
                                            "date",
                                            "details",
                                            "payment_method_id",
                                            "warehouse_id"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "expense": {
                                    "date": "2026-09-06",
                                    "warehouse_id": 1,
                                    "category_id": 2,
                                    "account_id": 1,
                                    "payment_method_id": 1,
                                    "amount": 120.5,
                                    "details": "Electricity bill August"
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses/create": {
            "get": {
                "operationId": "get_api_expenses_create",
                "tags": [
                    "Expenses"
                ],
                "summary": "Get lookups for the expense form",
                "description": "`Expenses_category`, the caller's `warehouses`, `accounts` and active `payment_methods`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@create",
                "x-source": "app/Http/Controllers/ExpensesController.php#L505-L529",
                "x-route-name": "expenses.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "expense_add",
                        "policy": "ExpensePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "ExpenseCategory",
                    "Account",
                    "PaymentMethod"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "Expenses_category": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses/documents/{id}": {
            "delete": {
                "operationId": "delete_api_expenses_documents_id",
                "tags": [
                    "Expenses"
                ],
                "summary": "Delete an expense document",
                "description": "Soft-deletes the document row and removes the file.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@deleteDocument",
                "x-source": "app/Http/Controllers/ExpensesController.php#L294-L325",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "expense_delete",
                        "policy": "ExpensePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`status: true`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Document deleted successfully"
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses/documents/{id}/download": {
            "get": {
                "operationId": "get_api_expenses_documents_id_download",
                "tags": [
                    "Expenses"
                ],
                "summary": "Download an expense document",
                "description": "Streams the stored file with its original name.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@downloadDocument",
                "x-source": "app/Http/Controllers/ExpensesController.php#L264-L291",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "expense_view",
                        "policy": "ExpensePolicy"
                    }
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses/{expense}": {
            "delete": {
                "operationId": "delete_api_expenses_expense",
                "tags": [
                    "Expenses"
                ],
                "summary": "Delete an expense",
                "description": "Soft-deletes the expense and adds its amount back to the account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@destroy",
                "x-source": "app/Http/Controllers/ExpensesController.php#L399-L433",
                "x-route-name": "expenses.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "expense_delete",
                        "policy": "ExpensePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Expense",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Expense id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_expenses_expense",
                "tags": [
                    "Expenses"
                ],
                "summary": "(Not implemented) Get an expense",
                "description": "Empty stub; returns an empty `200`. Use the edit endpoint.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@show",
                "x-source": "app/Http/Controllers/ExpensesController.php#L329-L333",
                "x-route-name": "expenses.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Expense id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_expenses_expense",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Expenses"
                ],
                "summary": "Update an expense",
                "description": "Restores the old amount to the old account, saves the new values and debits the new amount from the (possibly different) account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@update",
                "x-source": "app/Http/Controllers/ExpensesController.php#L337-L395",
                "x-route-name": "expenses.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "expense_edit",
                        "policy": "ExpensePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Expense",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Expense fields as a nested object: `date`, `account_id`, `category_id` (expense category), `warehouse_id`, `payment_method_id`, `amount`, `details` (description). Changing the account or amount adjusts the account balance."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "expense": {
                                        "properties": {
                                            "amount": {
                                                "x-inferred": true,
                                                "type": "number",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount."
                                            },
                                            "category_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Expense category ID."
                                            },
                                            "date": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "format": "date",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Expense date."
                                            },
                                            "details": {
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Description of the expense.",
                                                "type": "string"
                                            },
                                            "payment_method_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Payment method ID."
                                            },
                                            "warehouse_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Warehouse the expense belongs to."
                                            }
                                        },
                                        "required": [
                                            "amount",
                                            "category_id",
                                            "date",
                                            "details",
                                            "payment_method_id",
                                            "warehouse_id"
                                        ],
                                        "description": "Expense fields as a nested object: `date`, `account_id`, `category_id` (expense category), `warehouse_id`, `payment_method_id`, `amount`, `details` (description). Changing the account or amount adjusts the account balance.",
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_expenses_expense",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Expenses"
                ],
                "summary": "Update an expense",
                "description": "Restores the old amount to the old account, saves the new values and debits the new amount from the (possibly different) account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@update",
                "x-source": "app/Http/Controllers/ExpensesController.php#L337-L395",
                "x-route-name": "expenses.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "expense_edit",
                        "policy": "ExpensePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Expense",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Expense fields as a nested object: `date`, `account_id`, `category_id` (expense category), `warehouse_id`, `payment_method_id`, `amount`, `details` (description). Changing the account or amount adjusts the account balance."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "expense": {
                                        "properties": {
                                            "amount": {
                                                "x-inferred": true,
                                                "type": "number",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount."
                                            },
                                            "category_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Expense category ID."
                                            },
                                            "date": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "format": "date",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Expense date."
                                            },
                                            "details": {
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Description of the expense.",
                                                "type": "string"
                                            },
                                            "payment_method_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Payment method ID."
                                            },
                                            "warehouse_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Warehouse the expense belongs to."
                                            }
                                        },
                                        "required": [
                                            "amount",
                                            "category_id",
                                            "date",
                                            "details",
                                            "payment_method_id",
                                            "warehouse_id"
                                        ],
                                        "description": "Expense fields as a nested object: `date`, `account_id`, `category_id` (expense category), `warehouse_id`, `payment_method_id`, `amount`, `details` (description). Changing the account or amount adjusts the account balance.",
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/expenses/{expense}/edit": {
            "get": {
                "operationId": "get_api_expenses_expense_edit",
                "tags": [
                    "Expenses"
                ],
                "summary": "Get an expense for editing",
                "description": "`expense` (`warehouse_id, account_id, category_id, date, amount, details, payment_method_id`) plus the `expense_Category`, `warehouses`, `accounts`, `payment_methods` lookups.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@edit",
                "x-source": "app/Http/Controllers/ExpensesController.php#L533-L614",
                "x-route-name": "expenses.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "expense_edit",
                        "policy": "ExpensePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Expense",
                    "Warehouse",
                    "Account",
                    "ExpenseCategory",
                    "UserWarehouse",
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "expense",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Expense id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`expense` and lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "expense": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "expense_Category": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses/{id}/documents": {
            "get": {
                "operationId": "get_api_expenses_id_documents",
                "tags": [
                    "Expenses"
                ],
                "summary": "List documents attached to an expense",
                "description": "Files uploaded against the expense (`id, name, path, size, mime_type, created_at`), newest first.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@getDocuments",
                "x-source": "app/Http/Controllers/ExpensesController.php#L191-L207",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "expense_view",
                        "policy": "ExpensePolicy"
                    }
                ],
                "x-models": [
                    "Expense"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Expense id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`documents[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_expenses_id_documents",
                "tags": [
                    "Expenses"
                ],
                "summary": "Upload documents to an expense",
                "description": "Uploads one or more files (max 10 MB each) as `documents[]` into `/images/expense_documents/`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@uploadDocuments",
                "x-source": "app/Http/Controllers/ExpensesController.php#L210-L261",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "expense_edit",
                        "policy": "ExpensePolicy"
                    }
                ],
                "x-models": [
                    "Expense"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Expense id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "documents": {
                                        "type": "array",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Array of files.",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "maxLength": 10240,
                                            "x-laravel-rules": [
                                                "required",
                                                "file",
                                                "max:10240"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`documents[]` (new ids).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Documents uploaded successfully"
                                        },
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses_category": {
            "get": {
                "operationId": "get_api_expenses_category",
                "tags": [
                    "Expense Categories"
                ],
                "summary": "List expense categories",
                "description": "Paginated categories (own ones only without record view); `search` matches name or description.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryExpenseController@index",
                "x-source": "app/Http/Controllers/CategoryExpenseController.php#L15-L58",
                "x-route-name": "expenses_category.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "expense_view",
                        "policy": "ExpenseCategoryPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ExpenseCategory"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`Expenses_category[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "Expenses_category": {},
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_expenses_category",
                "tags": [
                    "Expense Categories"
                ],
                "summary": "Create an expense category",
                "description": "Creates a category owned by the caller.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryExpenseController@store",
                "x-source": "app/Http/Controllers/CategoryExpenseController.php#L62-L77",
                "x-route-name": "expenses_category.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "expense_add",
                        "policy": "ExpenseCategoryPolicy"
                    }
                ],
                "x-models": [
                    "ExpenseCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses_category/{expenses_category}": {
            "delete": {
                "operationId": "delete_api_expenses_category_expenses_category",
                "tags": [
                    "Expense Categories"
                ],
                "summary": "Delete an expense category",
                "description": "Soft-deletes the category.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryExpenseController@destroy",
                "x-source": "app/Http/Controllers/CategoryExpenseController.php#L119-L138",
                "x-route-name": "expenses_category.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "expense_delete",
                        "policy": "ExpenseCategoryPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "ExpenseCategory"
                ],
                "parameters": [
                    {
                        "name": "expenses_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_expenses_category_expenses_category",
                "tags": [
                    "Expense Categories"
                ],
                "summary": "(Not implemented) Get an expense category",
                "description": "Empty stub; returns an empty `200`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryExpenseController@show",
                "x-source": "app/Http/Controllers/CategoryExpenseController.php#L81-L85",
                "x-route-name": "expenses_category.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "expenses_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_expenses_category_expenses_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Expense Categories"
                ],
                "summary": "Update an expense category",
                "description": "Updates name and description.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryExpenseController@update",
                "x-source": "app/Http/Controllers/CategoryExpenseController.php#L89-L115",
                "x-route-name": "expenses_category.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "expense_edit",
                        "policy": "ExpenseCategoryPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "ExpenseCategory"
                ],
                "parameters": [
                    {
                        "name": "expenses_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_expenses_category_expenses_category",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Expense Categories"
                ],
                "summary": "Update an expense category",
                "description": "Updates name and description.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryExpenseController@update",
                "x-source": "app/Http/Controllers/CategoryExpenseController.php#L89-L115",
                "x-route-name": "expenses_category.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "expense_edit",
                        "policy": "ExpenseCategoryPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "ExpenseCategory"
                ],
                "parameters": [
                    {
                        "name": "expenses_category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/expenses_category_delete_by_selection": {
            "post": {
                "operationId": "post_api_expenses_category_delete_by_selection",
                "tags": [
                    "Expense Categories"
                ],
                "summary": "Delete several expense categories",
                "description": "Soft-deletes each id in `selectedIds`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "CategoryExpenseController@delete_by_selection",
                "x-source": "app/Http/Controllers/CategoryExpenseController.php#L142-L165",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "expense_delete",
                        "policy": "ExpenseCategoryPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "ExpenseCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of category ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/expenses_delete_by_selection": {
            "post": {
                "operationId": "post_api_expenses_delete_by_selection",
                "tags": [
                    "Expenses"
                ],
                "summary": "Delete several expenses",
                "description": "Soft-deletes each expense in `selectedIds`, re-balancing the accounts.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ExpensesController@delete_by_selection",
                "x-source": "app/Http/Controllers/ExpensesController.php#L437-L474",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "expense_delete",
                        "policy": "ExpensePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Expense",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of expense ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/feature_settings": {
            "get": {
                "operationId": "get_api_feature_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get feature toggles",
                "description": "Returns the feature switches shown on the Business Modules tab, with defaults applied for columns that do not exist yet.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@getFeatureSettings",
                "x-source": "app/Http/Controllers/SettingsController.php#L1146-L1168",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "business_modules",
                        "slug": "business_modules | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{features: {enable_3_decimal_pricing, enable_kitchen_display, kitchen_target_minutes, kitchen_auto_online_orders, show_product_gtin, product_image_resize, product_image_max_size, show_serial_tracking, enable_multi_pack_selling, enable_wholesale_pricing, enable_multi_currency, enable_pos_salesperson_switch, vehicle_fitment_enabled, auto_journal_enabled, allow_overselling}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "features": {
                                            "type": "object",
                                            "properties": {
                                                "enable_3_decimal_pricing": {
                                                    "type": "boolean"
                                                },
                                                "enable_kitchen_display": {
                                                    "type": "boolean"
                                                },
                                                "kitchen_target_minutes": {},
                                                "kitchen_auto_online_orders": {
                                                    "type": "boolean"
                                                },
                                                "show_product_gtin": {
                                                    "type": "boolean"
                                                },
                                                "product_image_resize": {
                                                    "type": "boolean"
                                                },
                                                "product_image_max_size": {
                                                    "type": "integer"
                                                },
                                                "show_serial_tracking": {
                                                    "type": "boolean"
                                                },
                                                "enable_multi_pack_selling": {
                                                    "type": "boolean"
                                                },
                                                "enable_wholesale_pricing": {
                                                    "type": "boolean"
                                                },
                                                "enable_multi_currency": {
                                                    "type": "boolean"
                                                },
                                                "enable_pos_salesperson_switch": {
                                                    "type": "boolean"
                                                },
                                                "vehicle_fitment_enabled": {
                                                    "type": "boolean"
                                                },
                                                "auto_journal_enabled": {
                                                    "type": "boolean"
                                                },
                                                "allow_overselling": {
                                                    "type": "boolean"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_feature_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Update feature toggles",
                "description": "Partial update: only keys present in the payload are written. Boolean keys accept `1`/`0`/`true`/`false`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@updateFeatureSettings",
                "x-source": "app/Http/Controllers/SettingsController.php#L1170-L1209",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "business_modules",
                        "slug": "business_modules | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "kitchen_target_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Target preparation minutes for the KDS.",
                                        "type": "integer"
                                    },
                                    "product_image_max_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Max edge in px for product image resize.",
                                        "type": "integer"
                                    },
                                    "enable_3_decimal_pricing": {
                                        "type": "boolean",
                                        "description": "Use three decimals for prices/quantities.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "enable_kitchen_display": {
                                        "type": "boolean",
                                        "description": "Enable the Kitchen Display System.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "kitchen_auto_online_orders": {
                                        "type": "boolean",
                                        "description": "Auto-send online orders to the kitchen.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "show_product_gtin": {
                                        "type": "boolean",
                                        "description": "Show GTIN on products.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "product_image_resize": {
                                        "type": "boolean",
                                        "description": "Resize product images on upload.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "show_serial_tracking": {
                                        "type": "boolean",
                                        "description": "Enable serial-number tracking UI.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "enable_multi_pack_selling": {
                                        "type": "boolean",
                                        "description": "Enable multi-pack selling.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "enable_wholesale_pricing": {
                                        "type": "boolean",
                                        "description": "Enable wholesale price tiers.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "enable_multi_currency": {
                                        "type": "boolean",
                                        "description": "Allow per-document currency.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "enable_pos_salesperson_switch": {
                                        "type": "boolean",
                                        "description": "Allow switching the salesperson in POS.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "vehicle_fitment_enabled": {
                                        "type": "boolean",
                                        "description": "Enable vehicle fitment module.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "auto_journal_enabled": {
                                        "type": "boolean",
                                        "description": "Auto-post accounting journals.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "allow_overselling": {
                                        "type": "boolean",
                                        "description": "Allow negative stock on sale.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/assignments": {
            "get": {
                "operationId": "get_api_fleet_assignments",
                "tags": [
                    "Fleet: Assignments"
                ],
                "summary": "List assignments",
                "description": "Paginated vehicle assignments (vehicle → driver/employee) with start/end and status. Filter by `vehicle_id`, `employee_id` or `status`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetAssignmentController@index",
                "x-source": "app/Http/Controllers/FleetAssignmentController.php#L21-L84",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "VehicleAssignmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "VehicleAssignment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "employee_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Driver."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`active`, `completed`, `cancelled`."
                    },
                    {
                        "name": "vehicle_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Vehicle."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`assignments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "assignments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_fleet_assignments",
                "tags": [
                    "Fleet: Assignments"
                ],
                "summary": "Assign a vehicle",
                "description": "Refused if the vehicle already has an active assignment. Updates the vehicle's driver.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetAssignmentController@store",
                "x-source": "app/Http/Controllers/FleetAssignmentController.php#L86-L105",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "VehicleAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "VehicleAssignment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "destination": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Destination."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Driver."
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End (>= start)."
                                    },
                                    "end_odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Odometer at end."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "purpose": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purpose."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "start_odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Odometer at start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,completed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`active`, `completed`, `cancelled`."
                                    },
                                    "vehicle_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "vehicles,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:vehicles,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle."
                                    }
                                },
                                "required": [
                                    "employee_id",
                                    "start_date",
                                    "status",
                                    "vehicle_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle_id": {},
                                        "employee_id": {},
                                        "start_date": {},
                                        "end_date": {},
                                        "start_odometer": {},
                                        "end_odometer": {},
                                        "purpose": {},
                                        "destination": {},
                                        "status": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/assignments/delete/by_selection": {
            "post": {
                "operationId": "post_api_fleet_assignments_delete_by_selection",
                "tags": [
                    "Fleet: Assignments"
                ],
                "summary": "Delete selected assignments",
                "description": "Bulk delete of assignments by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetAssignmentController@deleteBySelection",
                "x-source": "app/Http/Controllers/FleetAssignmentController.php#L158-L166",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "VehicleAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "VehicleAssignment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Assignment ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/assignments/{id}": {
            "delete": {
                "operationId": "delete_api_fleet_assignments_id",
                "tags": [
                    "Fleet: Assignments"
                ],
                "summary": "Delete an assignment",
                "description": "Deletes an assignment; the vehicle becomes available.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetAssignmentController@destroy",
                "x-source": "app/Http/Controllers/FleetAssignmentController.php#L149-L156",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "VehicleAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "VehicleAssignment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Assignment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_fleet_assignments_id",
                "tags": [
                    "Fleet: Assignments"
                ],
                "summary": "Update an assignment",
                "description": "Updates an assignment (driver, dates, notes, status). Closing it (`status = returned`) frees the vehicle.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetAssignmentController@update",
                "x-source": "app/Http/Controllers/FleetAssignmentController.php#L107-L125",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "VehicleAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "VehicleAssignment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Assignment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "destination": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Destination."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Driver."
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "end_odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End odometer."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "purpose": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purpose."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "start_odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start odometer."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,completed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "vehicle_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "vehicles,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:vehicles,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle."
                                    }
                                },
                                "required": [
                                    "employee_id",
                                    "start_date",
                                    "status",
                                    "vehicle_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle_id": {},
                                        "employee_id": {},
                                        "start_date": {},
                                        "end_date": {},
                                        "start_odometer": {},
                                        "end_odometer": {},
                                        "purpose": {},
                                        "destination": {},
                                        "status": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/assignments/{id}/close": {
            "post": {
                "operationId": "post_api_fleet_assignments_id_close",
                "tags": [
                    "Fleet: Assignments"
                ],
                "summary": "Close an assignment",
                "description": "Marks it `completed` with the final reading and frees the vehicle.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetAssignmentController@close",
                "x-source": "app/Http/Controllers/FleetAssignmentController.php#L128-L147",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "VehicleAssignmentPolicy"
                    }
                ],
                "x-models": [
                    "VehicleAssignment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Assignment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Return date (default now)."
                                    },
                                    "end_odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Final odometer."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/dashboard": {
            "get": {
                "operationId": "get_api_fleet_dashboard",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Fleet dashboard",
                "description": "Counts (`total`, `by_status`, `by_type`, `active`, `in_maintenance`, `assigned`), fuel / maintenance costs for the month and overall, `alerts` (renewals and services due within 30 days or overdue), 12-month `cost_trend` and `recent_maintenance`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@dashboard",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L223-L278",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "fleet_vehicles_view",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle",
                    "VehicleAssignment",
                    "VehicleFuelLog",
                    "VehicleMaintenance"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "by_status": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_type": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "active": {
                                            "type": "integer"
                                        },
                                        "in_maintenance": {
                                            "type": "integer"
                                        },
                                        "assigned": {
                                            "type": "integer"
                                        },
                                        "fuel_cost_month": {
                                            "type": "number"
                                        },
                                        "maintenance_cost_month": {
                                            "type": "number"
                                        },
                                        "fuel_cost_total": {
                                            "type": "number"
                                        },
                                        "maintenance_cost_total": {
                                            "type": "number"
                                        },
                                        "alerts": {},
                                        "cost_trend": {},
                                        "recent_maintenance": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/fuel-logs": {
            "get": {
                "operationId": "get_api_fleet_fuel_logs",
                "tags": [
                    "Fleet: Fuel Logs"
                ],
                "summary": "List fuel logs",
                "description": "Paginated with `totals` (quantity and cost).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetFuelLogController@index",
                "x-source": "app/Http/Controllers/FleetFuelLogController.php#L17-L80",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "VehicleFuelLogPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "VehicleFuelLog"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "employee_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Driver."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "vehicle_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Vehicle."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`fuel_logs[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "fuel_logs": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_fleet_fuel_logs",
                "tags": [
                    "Fleet: Fuel Logs"
                ],
                "summary": "Log a refuel",
                "description": "`total_cost` is computed from `quantity × unit_price` when omitted. The vehicle odometer is advanced.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetFuelLogController@store",
                "x-source": "app/Http/Controllers/FleetFuelLogController.php#L82-L95",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "VehicleFuelLogPolicy"
                    }
                ],
                "x-models": [
                    "VehicleFuelLog"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Driver."
                                    },
                                    "full_tank": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Filled to full (enables efficiency calc).",
                                        "type": "boolean"
                                    },
                                    "log_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Odometer reading."
                                    },
                                    "quantity": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Litres."
                                    },
                                    "station": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Station."
                                    },
                                    "total_cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Total paid."
                                    },
                                    "unit_price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Price per litre."
                                    },
                                    "vehicle_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "vehicles,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:vehicles,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle."
                                    }
                                },
                                "required": [
                                    "log_date",
                                    "odometer",
                                    "quantity",
                                    "vehicle_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle_id": {},
                                        "employee_id": {},
                                        "log_date": {},
                                        "odometer": {},
                                        "quantity": {
                                            "type": "integer"
                                        },
                                        "unit_price": {},
                                        "total_cost": {
                                            "type": "integer"
                                        },
                                        "station": {},
                                        "full_tank": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/fuel-logs/delete/by_selection": {
            "post": {
                "operationId": "post_api_fleet_fuel_logs_delete_by_selection",
                "tags": [
                    "Fleet: Fuel Logs"
                ],
                "summary": "Delete selected fuel logs",
                "description": "Bulk delete of fuel logs by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetFuelLogController@deleteBySelection",
                "x-source": "app/Http/Controllers/FleetFuelLogController.php#L120-L128",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "VehicleFuelLogPolicy"
                    }
                ],
                "x-models": [
                    "VehicleFuelLog"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Log ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/fuel-logs/{id}": {
            "delete": {
                "operationId": "delete_api_fleet_fuel_logs_id",
                "tags": [
                    "Fleet: Fuel Logs"
                ],
                "summary": "Delete a fuel log",
                "description": "Deletes a fuel log entry.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetFuelLogController@destroy",
                "x-source": "app/Http/Controllers/FleetFuelLogController.php#L111-L118",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "VehicleFuelLogPolicy"
                    }
                ],
                "x-models": [
                    "VehicleFuelLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Log id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_fleet_fuel_logs_id",
                "tags": [
                    "Fleet: Fuel Logs"
                ],
                "summary": "Update a fuel log",
                "description": "Updates a fuel log with the same fields as creation (date, litres, cost, odometer, station).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetFuelLogController@update",
                "x-source": "app/Http/Controllers/FleetFuelLogController.php#L97-L109",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "VehicleFuelLogPolicy"
                    }
                ],
                "x-models": [
                    "VehicleFuelLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Log id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Driver."
                                    },
                                    "full_tank": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full tank.",
                                        "type": "boolean"
                                    },
                                    "log_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Odometer."
                                    },
                                    "quantity": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Litres."
                                    },
                                    "station": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Station."
                                    },
                                    "total_cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Total."
                                    },
                                    "unit_price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unit price."
                                    },
                                    "vehicle_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "vehicles,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:vehicles,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle."
                                    }
                                },
                                "required": [
                                    "log_date",
                                    "odometer",
                                    "quantity",
                                    "vehicle_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle_id": {},
                                        "employee_id": {},
                                        "log_date": {},
                                        "odometer": {},
                                        "quantity": {
                                            "type": "integer"
                                        },
                                        "unit_price": {},
                                        "total_cost": {
                                            "type": "integer"
                                        },
                                        "station": {},
                                        "full_tank": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/maintenances": {
            "get": {
                "operationId": "get_api_fleet_maintenances",
                "tags": [
                    "Fleet: Maintenance"
                ],
                "summary": "List maintenance records",
                "description": "Paginated maintenance records with vehicle, type, cost, dates and status. Filter by `vehicle_id`, `status`, `type` and date range.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetMaintenanceController@index",
                "x-source": "app/Http/Controllers/FleetMaintenanceController.php#L18-L82",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "VehicleMaintenancePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "VehicleMaintenance"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Service date to."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Service date from."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Type."
                    },
                    {
                        "name": "vehicle_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Vehicle."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`maintenances[]`, `totalRows`, `total_cost`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "total_cost": {},
                                        "maintenances": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_fleet_maintenances",
                "tags": [
                    "Fleet: Maintenance"
                ],
                "summary": "Create a maintenance record",
                "description": "Records a maintenance job for a vehicle: type, description, dates, cost, odometer and service provider. Vehicles in maintenance are marked unavailable.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetMaintenanceController@store",
                "x-source": "app/Http/Controllers/FleetMaintenanceController.php#L84-L97",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "VehicleMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "VehicleMaintenance"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cost."
                                    },
                                    "next_service_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Next service due date."
                                    },
                                    "next_service_odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Next service due odometer."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Odometer at service."
                                    },
                                    "service_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Service date."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "in_progress",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:scheduled,in_progress,completed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "service",
                                            "repair",
                                            "tyres",
                                            "inspection",
                                            "insurance",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:service,repair,tyres,inspection,insurance,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "vehicle_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "vehicles,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:vehicles,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle."
                                    },
                                    "vendor": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Garage / vendor."
                                    }
                                },
                                "required": [
                                    "service_date",
                                    "status",
                                    "title",
                                    "type",
                                    "vehicle_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle_id": {},
                                        "type": {},
                                        "title": {},
                                        "service_date": {},
                                        "odometer": {},
                                        "cost": {},
                                        "vendor": {},
                                        "status": {},
                                        "next_service_date": {},
                                        "next_service_odometer": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/maintenances/delete/by_selection": {
            "post": {
                "operationId": "post_api_fleet_maintenances_delete_by_selection",
                "tags": [
                    "Fleet: Maintenance"
                ],
                "summary": "Delete selected maintenance records",
                "description": "Bulk delete of maintenance records by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetMaintenanceController@deleteBySelection",
                "x-source": "app/Http/Controllers/FleetMaintenanceController.php#L122-L130",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "VehicleMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "VehicleMaintenance"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Record ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/maintenances/{id}": {
            "delete": {
                "operationId": "delete_api_fleet_maintenances_id",
                "tags": [
                    "Fleet: Maintenance"
                ],
                "summary": "Delete a maintenance record",
                "description": "Deletes a maintenance record.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetMaintenanceController@destroy",
                "x-source": "app/Http/Controllers/FleetMaintenanceController.php#L113-L120",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "VehicleMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "VehicleMaintenance"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Record id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_fleet_maintenances_id",
                "tags": [
                    "Fleet: Maintenance"
                ],
                "summary": "Update a maintenance record",
                "description": "Updates a maintenance record with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetMaintenanceController@update",
                "x-source": "app/Http/Controllers/FleetMaintenanceController.php#L99-L111",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "VehicleMaintenancePolicy"
                    }
                ],
                "x-models": [
                    "VehicleMaintenance"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Record id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cost."
                                    },
                                    "next_service_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Next date."
                                    },
                                    "next_service_odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Next odometer."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Odometer."
                                    },
                                    "service_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "in_progress",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:scheduled,in_progress,completed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "service",
                                            "repair",
                                            "tyres",
                                            "inspection",
                                            "insurance",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:service,repair,tyres,inspection,insurance,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "vehicle_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "vehicles,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:vehicles,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle."
                                    },
                                    "vendor": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vendor."
                                    }
                                },
                                "required": [
                                    "service_date",
                                    "status",
                                    "title",
                                    "type",
                                    "vehicle_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle_id": {},
                                        "type": {},
                                        "title": {},
                                        "service_date": {},
                                        "odometer": {},
                                        "cost": {},
                                        "vendor": {},
                                        "status": {},
                                        "next_service_date": {},
                                        "next_service_odometer": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/meta": {
            "get": {
                "operationId": "get_api_fleet_meta",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Fleet form lookups",
                "description": "Selects shared by the vehicle form and every fleet log form.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@meta",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L105-L125",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "fleet_vehicles_view",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle",
                    "Warehouse",
                    "Employee"
                ],
                "responses": {
                    "200": {
                        "description": "`vehicles[] {id, name, plate_number, label, odometer, status}`, `warehouses[]`, `employees[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicles": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/reports/costs": {
            "get": {
                "operationId": "get_api_fleet_reports_costs",
                "tags": [
                    "Fleet: Reports"
                ],
                "summary": "Running-cost report",
                "description": "Per vehicle: fuel cost / quantity, maintenance cost / count, `total_cost`, `distance`, `cost_per_distance`, `efficiency`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetReportController@costs",
                "x-source": "app/Http/Controllers/FleetReportController.php#L28-L66",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "fleet_reports",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Vehicle"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Type."
                    },
                    {
                        "name": "vehicle_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Vehicle."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "vehicle_name": {},
                                        "plate_number": {},
                                        "type": {},
                                        "status": {},
                                        "warehouse_name": {},
                                        "fuel_cost": {
                                            "type": "number"
                                        },
                                        "fuel_quantity": {
                                            "type": "number"
                                        },
                                        "maintenance_cost": {
                                            "type": "number"
                                        },
                                        "maintenance_count": {
                                            "type": "integer"
                                        },
                                        "total_cost": {
                                            "type": "number"
                                        },
                                        "distance": {
                                            "type": "number"
                                        },
                                        "cost_per_distance": {
                                            "type": "number"
                                        },
                                        "efficiency": {},
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/reports/drivers": {
            "get": {
                "operationId": "get_api_fleet_reports_drivers",
                "tags": [
                    "Fleet: Reports"
                ],
                "summary": "Driver report",
                "description": "Per driver: trips, open trips, distance, fuel quantity and cost.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetReportController@drivers",
                "x-source": "app/Http/Controllers/FleetReportController.php#L145-L195",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "fleet_reports",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Vehicle",
                    "VehicleAssignment",
                    "VehicleFuelLog",
                    "Employee"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "driver_name": {},
                                        "trips": {
                                            "type": "integer"
                                        },
                                        "open_trips": {
                                            "type": "integer"
                                        },
                                        "distance": {
                                            "type": "number"
                                        },
                                        "fuel_quantity": {
                                            "type": "number"
                                        },
                                        "fuel_cost": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/reports/fuel": {
            "get": {
                "operationId": "get_api_fleet_reports_fuel",
                "tags": [
                    "Fleet: Reports"
                ],
                "summary": "Fuel report",
                "description": "Per vehicle: fill-ups, quantity, cost, average unit price, distance, efficiency and cost per distance.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetReportController@fuel",
                "x-source": "app/Http/Controllers/FleetReportController.php#L69-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "fleet_reports",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Vehicle"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Type."
                    },
                    {
                        "name": "vehicle_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Vehicle."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "vehicle_name": {},
                                        "plate_number": {},
                                        "fuel_type": {},
                                        "fill_ups": {
                                            "type": "integer"
                                        },
                                        "quantity": {
                                            "type": "number"
                                        },
                                        "fuel_cost": {
                                            "type": "number"
                                        },
                                        "avg_unit_price": {
                                            "type": "number"
                                        },
                                        "distance": {
                                            "type": "number"
                                        },
                                        "efficiency": {},
                                        "cost_per_distance": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/reports/maintenance": {
            "get": {
                "operationId": "get_api_fleet_reports_maintenance",
                "tags": [
                    "Fleet: Reports"
                ],
                "summary": "Maintenance report",
                "description": "Per vehicle spend split into service / repair / tyres / other.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetReportController@maintenance",
                "x-source": "app/Http/Controllers/FleetReportController.php#L104-L142",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "fleet_reports",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "VehicleMaintenance"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Type."
                    },
                    {
                        "name": "vehicle_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Vehicle."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "vehicle_name": {},
                                        "plate_number": {},
                                        "service_cost": {},
                                        "repair_cost": {},
                                        "tyres_cost": {},
                                        "other_cost": {
                                            "type": "number"
                                        },
                                        "entries": {
                                            "type": "integer"
                                        },
                                        "total_cost": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/vehicles": {
            "get": {
                "operationId": "get_api_fleet_vehicles",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "List vehicles",
                "description": "Paginated with warehouse and driver. `search` matches name, plate, VIN, make or model.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@index",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L43-L102",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "fleet_vehicles_view",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Vehicle"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "employee_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Driver."
                    },
                    {
                        "name": "expiring",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = insurance / registration / inspection expiring within 30 days."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Vehicle type."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`vehicles[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "vehicles": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_fleet_vehicles",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Create a vehicle",
                "description": "Multipart (optional `image`, max 5 MB).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@store",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L127-L139",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "fleet_vehicles_add",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "color": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Colour."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default driver."
                                    },
                                    "fuel_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "petrol",
                                            "diesel",
                                            "electric",
                                            "hybrid",
                                            "lpg",
                                            "cng"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:petrol,diesel,electric,hybrid,lpg,cng"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Fuel."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "inspection_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Inspection expiry."
                                    },
                                    "insurance_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Insurance expiry."
                                    },
                                    "insurance_policy": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Policy number."
                                    },
                                    "insurance_provider": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Insurer."
                                    },
                                    "make": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Make."
                                    },
                                    "model": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Model."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Current odometer."
                                    },
                                    "plate_number": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Plate."
                                    },
                                    "purchase_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Purchase date."
                                    },
                                    "purchase_price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Purchase price."
                                    },
                                    "registration_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Registration expiry."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "maintenance",
                                            "inactive",
                                            "sold"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,maintenance,inactive,sold"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "tank_capacity": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tank capacity (litres)."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "car",
                                            "van",
                                            "truck",
                                            "bus",
                                            "motorcycle",
                                            "forklift",
                                            "trailer",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:car,van,truck,bus,motorcycle,forklift,trailer,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle type."
                                    },
                                    "vin": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "VIN."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Home warehouse."
                                    },
                                    "year": {
                                        "type": "integer",
                                        "minimum": 1900,
                                        "maximum": 2200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1900",
                                            "max:2200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    }
                                },
                                "required": [
                                    "fuel_type",
                                    "name",
                                    "plate_number",
                                    "status",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "plate_number": {},
                                        "vin": {},
                                        "make": {},
                                        "model": {},
                                        "year": {},
                                        "color": {},
                                        "type": {},
                                        "status": {},
                                        "warehouse_id": {},
                                        "employee_id": {},
                                        "fuel_type": {},
                                        "tank_capacity": {},
                                        "odometer": {},
                                        "purchase_date": {},
                                        "purchase_price": {},
                                        "insurance_provider": {},
                                        "insurance_policy": {},
                                        "insurance_expiry": {},
                                        "registration_expiry": {},
                                        "inspection_expiry": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/vehicles/delete/by_selection": {
            "post": {
                "operationId": "post_api_fleet_vehicles_delete_by_selection",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Delete selected vehicles",
                "description": "Bulk soft-delete of vehicles by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@deleteBySelection",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L205-L213",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "fleet_vehicles_delete",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Vehicle ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/vehicles/{id}": {
            "delete": {
                "operationId": "delete_api_fleet_vehicles_id",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Delete a vehicle",
                "description": "Soft-deletes a vehicle and its image.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@destroy",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L196-L203",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "fleet_vehicles_delete",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Vehicle id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_fleet_vehicles_id",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Get a vehicle",
                "description": "Vehicle with `stats` (trips, distance, fuel and maintenance totals).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@show",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L141-L156",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "fleet_vehicles_view",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Vehicle id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`vehicle`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/vehicles/{id}/edit": {
            "get": {
                "operationId": "get_api_fleet_vehicles_id_edit",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Edit-form data for a vehicle",
                "description": "The vehicle plus lookups (drivers, warehouses, types) for the edit form.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@edit",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L158-L171",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "fleet_vehicles_edit",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Vehicle id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`vehicle` with `image_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/fleet/vehicles/{id}/update": {
            "post": {
                "operationId": "post_api_fleet_vehicles_id_update",
                "tags": [
                    "Fleet: Vehicles"
                ],
                "summary": "Update a vehicle",
                "description": "Multipart POST (same fields as create). Send `remove_image=1` to drop the photo.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "FleetVehicleController@update",
                "x-source": "app/Http/Controllers/FleetVehicleController.php#L173-L194",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "fleet_vehicles_edit",
                        "policy": "VehiclePolicy"
                    }
                ],
                "x-models": [
                    "Vehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Vehicle id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "color": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Colour."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default driver."
                                    },
                                    "fuel_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "petrol",
                                            "diesel",
                                            "electric",
                                            "hybrid",
                                            "lpg",
                                            "cng"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:petrol,diesel,electric,hybrid,lpg,cng"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Fuel."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "inspection_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Inspection expiry."
                                    },
                                    "insurance_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Insurance expiry."
                                    },
                                    "insurance_policy": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Policy number."
                                    },
                                    "insurance_provider": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Insurer."
                                    },
                                    "make": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Make."
                                    },
                                    "model": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Model."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "odometer": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Current odometer."
                                    },
                                    "plate_number": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Plate."
                                    },
                                    "purchase_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Purchase date."
                                    },
                                    "purchase_price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Purchase price."
                                    },
                                    "registration_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Registration expiry."
                                    },
                                    "remove_image": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remove the current photo.",
                                        "type": "boolean"
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "maintenance",
                                            "inactive",
                                            "sold"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,maintenance,inactive,sold"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "tank_capacity": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tank capacity (litres)."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "car",
                                            "van",
                                            "truck",
                                            "bus",
                                            "motorcycle",
                                            "forklift",
                                            "trailer",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:car,van,truck,bus,motorcycle,forklift,trailer,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Vehicle type."
                                    },
                                    "vin": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "VIN."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Home warehouse."
                                    },
                                    "year": {
                                        "type": "integer",
                                        "minimum": 1900,
                                        "maximum": 2200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1900",
                                            "max:2200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    }
                                },
                                "required": [
                                    "fuel_type",
                                    "name",
                                    "plate_number",
                                    "status",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "plate_number": {},
                                        "vin": {},
                                        "make": {},
                                        "model": {},
                                        "year": {},
                                        "color": {},
                                        "type": {},
                                        "status": {},
                                        "warehouse_id": {},
                                        "employee_id": {},
                                        "fuel_type": {},
                                        "tank_capacity": {},
                                        "odometer": {},
                                        "purchase_date": {},
                                        "purchase_price": {},
                                        "insurance_provider": {},
                                        "insurance_policy": {},
                                        "insurance_expiry": {},
                                        "registration_expiry": {},
                                        "inspection_expiry": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/generate_new_backup": {
            "get": {
                "operationId": "get_api_generate_new_backup",
                "tags": [
                    "Backups"
                ],
                "summary": "Generate a backup",
                "description": "Runs the `database:backup` artisan command (mysqldump via `DUMP_PATH`) and, if cloud backup is enabled in settings, uploads the file to the configured provider. `cloud` describes the upload outcome.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "BackupController@Generate_Backup",
                "x-source": "app/Http/Controllers/BackupController.php#L41-L166",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "backup",
                        "slug": "backup | setting_system",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, message, cloud: {provider, uploaded, error?}|null}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "cloud": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "500": {
                        "description": "Backup command failed; `error` holds the tool output.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Backup generation error"
                                        },
                                        "error": {},
                                        "cloud": {
                                            "nullable": true,
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get-logo-setting": {
            "get": {
                "operationId": "get_api_get_logo_setting",
                "tags": [
                    "Health & Utilities"
                ],
                "summary": "Get the application logo",
                "description": "Returns the logo file name from System Settings so the login page can show it before any user is authenticated. Prefix with `/images/` to build the URL.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "`logo` is the file name or `null` when no settings row exists."
                    }
                },
                "security": []
            }
        },
        "/api/getAccessToken": {
            "post": {
                "operationId": "post_api_getAccessToken",
                "tags": [
                    "Authentication"
                ],
                "summary": "Log in and get an access token",
                "description": "Authenticates a staff user with email and password and issues a Passport personal access token.\n\nOn success the token is returned in the body as `Stocky_token` **and** written to a `Stocky_token` cookie scoped to the current domain (this is how the admin SPA authenticates). API clients should store the token and send it as `Authorization: Bearer <token>`.\n\nNote the endpoint always answers with HTTP 200: check the `status` field. `status: false` means wrong credentials, `status: \"NotActive\"` means the account exists but is disabled.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "AuthController@getAccessToken",
                "x-source": "app/Http/Controllers/AuthController.php#L12-L47",
                "x-middleware": [
                    "api"
                ],
                "x-notes": [
                    "The issued token does not expire on its own; it is revoked by `POST /api/logout`, by the inactivity timeout, or from Settings → Security → Active sessions.",
                    "Every authenticated request also passes the `Is_Active` middleware: if the user is deactivated after logging in, the next request logs them out."
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "The user's login email."
                                    },
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "The user's password (plain text over HTTPS)."
                                    }
                                },
                                "required": [
                                    "email",
                                    "password"
                                ]
                            },
                            "example": {
                                "email": "admin@example.com",
                                "password": "123456"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Login result. `status: true` with `Stocky_token` and `username` on success; `status: false` + `message: \"Incorrect Login\"` for bad credentials; `status: \"NotActive\"` when the user is disabled.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Incorrect Login"
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "Stocky_token": {},
                                        "username": {}
                                    }
                                },
                                "example": {
                                    "Stocky_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9…",
                                    "username": "William Castillo",
                                    "status": true
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/api/get_Products_by_purchase/{id}": {
            "get": {
                "operationId": "get_api_get_Products_by_purchase_id",
                "tags": [
                    "Purchases"
                ],
                "summary": "Get purchase lines for a return",
                "description": "Pre-fills the *create purchase return* form: `purchase_return` defaults (`supplier_id, warehouse_id, purchase_id, statut completed, zeros`) and `details[]` with every purchased line (quantity, unit, cost, taxes, `stock` currently in the warehouse, serials).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@get_Products_by_purchase",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1629-L1764",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchase_Returns_add",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchase_return` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchase_return": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_Products_by_sale/{id}": {
            "get": {
                "operationId": "get_api_get_Products_by_sale_id",
                "tags": [
                    "Sales"
                ],
                "summary": "Get sale lines for a return",
                "description": "Pre-fills the *create sale return* form from a sale: `sale_return` header defaults (`client_id, warehouse_id, sale_id, statut received, zeros`) and `details[]` with every sold line (quantities sold, unit, price, taxes, `stock` available in the warehouse, serial numbers).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@get_Products_by_sale",
                "x-source": "app/Http/Controllers/SalesController.php#L3418-L3565",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sale_Returns_add",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale_return` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale_return": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_Products_by_warehouse/{id}": {
            "get": {
                "operationId": "get_api_get_Products_by_warehouse_id",
                "tags": [
                    "Products"
                ],
                "summary": "List sellable products in a warehouse",
                "description": "Products available in one warehouse in the flat shape used by POS and the document forms (one row per product **or per variant**): `id, product_variant_id, code, barcode, name, Variant, image, product_type, unit`, prices (`Unit_price`, `Net_price`, `wholesale_price`, `min_price`), tax/discount fields, `qte_sale` / `qte_purchase` (stock in sale/purchase units), `is_batch_tracked`, `is_imei`, `packs`, `wholesale_tiers`, `promo_*` fields when a promotion applies, and `combo_available_qty` for combos.\n\nOnly active products are returned; with `is_sale=1` products flagged *not for selling* are excluded. When the global *Allow overselling* setting is on, zero-stock products are still listed. The warehouse must be assigned to the caller (403 otherwise).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@Products_by_Warehouse",
                "x-source": "app/Http/Controllers/ProductsController.php#L1960-L2180",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Setting",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Warehouse id."
                    },
                    {
                        "name": "is_sale",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = exclude products marked `not_selling` (POS / sales context)."
                    },
                    {
                        "name": "product_combo",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = include combo products; `0`/omit = exclude combos."
                    },
                    {
                        "name": "product_service",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = include services (non stock-managed products); `0` = stock-managed products only."
                    },
                    {
                        "name": "stock",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = only products with stock `> 0` (unless overselling is allowed); `0`/omit = no stock filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of product/variant rows.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_Settings_data": {
            "get": {
                "operationId": "get_api_get_Settings_data",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get settings bundle for the app shell",
                "description": "Returns the global settings row plus every lookup list the UI needs to render forms (currencies, default client/warehouse candidates, SMS gateways, timezones, languages). Any authenticated user may call it: sensitive values (cloud-backup secrets, tokens) are masked and replaced with `*_has_*` booleans unless `include_secrets` is passed by a user who also holds `setting_system`. Referenced defaults that no longer exist (deleted currency/client/warehouse) come back as empty strings so the form does not point at a dead record.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@getSettings",
                "x-source": "app/Http/Controllers/SettingsController.php#L1560-L1792",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Setting",
                    "Currency",
                    "Client",
                    "Warehouse",
                    "sms_gateway",
                    "Account",
                    "PaymentMethod",
                    "UserWarehouse",
                    "Language"
                ],
                "parameters": [
                    {
                        "name": "include_secrets",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Pass `1` to include raw backup/cloud credentials in the response. Silently ignored for users without `setting_system`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`settings` (object with company info, defaults, prefixes, feature flags, backup config, `pharmacy_mode_supported`, `date_format`, `price_format`, `export_settings`), `currencies`, `clients`, `warehouses`, `sms_gateway`, `zones_array` (timezones), `languages`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {},
                                        "currencies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sms_gateway": {},
                                        "zones_array": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "languages": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "500": {
                        "description": "`{statut: \"error\"}` when the settings row is missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statut": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_Settings_data_api": {
            "get": {
                "operationId": "get_api_get_Settings_data_api",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get settings bundle for the Settings screen",
                "description": "Same payload as `GET /api/get_Settings_data` but guarded by `setting_system` and extended with `accounts` and `payment_methods` for the default-account / default-payment-method selectors. Use this from the System Settings page; use the unguarded variant for the app shell.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@get_Settings_data_api",
                "x-source": "app/Http/Controllers/SettingsController.php#L788-L1026",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Currency",
                    "Client",
                    "Warehouse",
                    "sms_gateway",
                    "Account",
                    "PaymentMethod",
                    "UserWarehouse",
                    "Language"
                ],
                "parameters": [
                    {
                        "name": "include_secrets",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Pass `1` to include raw cloud-backup credentials instead of the masked `*_has_*` booleans."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {},
                                        "currencies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sms_gateway": {},
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "zones_array": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "languages": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statut": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_accounts_by_employee": {
            "get": {
                "operationId": "get_api_get_accounts_by_employee",
                "tags": [
                    "Employees"
                ],
                "summary": "Bank accounts of an employee",
                "description": "Paginated bank accounts (`limit`, `page`).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@get_accounts_by_employee",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L351-L379",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "view_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "EmployeeAccount"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Employee id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`accounts_bank[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "accounts_bank": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_all_company": {
            "get": {
                "operationId": "get_api_get_all_company",
                "tags": [
                    "Companies"
                ],
                "summary": "List all companies (lookup)",
                "description": "`{id, name}` of every company, newest first. No permission check beyond login.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\CompanyController@Get_all_Company",
                "x-source": "app/Http/Controllers/hrm/CompanyController.php#L132-L139",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "Array of companies.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_all_departments": {
            "get": {
                "operationId": "get_api_get_all_departments",
                "tags": [
                    "Departments"
                ],
                "summary": "List all departments (lookup)",
                "description": "`{id, department}` for every department.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DepartmentsController@Get_all_Departments",
                "x-source": "app/Http/Controllers/hrm/DepartmentsController.php#L161-L166",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Department"
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_appearance_settings": {
            "get": {
                "operationId": "get_api_get_appearance_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get appearance settings",
                "description": "Branding values for the Appearance tab: app name, page title suffix, logo/favicon filenames, footer credits, `hide_site_name`, `customize_button_visible` and the login-page hero/panel texts and background colour.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@get_appearance_settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L1871-L1908",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "appearance_settings",
                        "slug": "appearance_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{settings: {...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "500": {
                        "description": "`{statut: \"error\"}` when the settings row is missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statut": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_backup": {
            "get": {
                "operationId": "get_api_get_backup",
                "tags": [
                    "Backups"
                ],
                "summary": "List backups",
                "description": "Backup files in `storage/app/public/backup` with human-readable sizes.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "BackupController@Get_Backup",
                "x-source": "app/Http/Controllers/BackupController.php#L15-L37",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "backup",
                        "slug": "backup | setting_system",
                        "policy": "UserPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{backups: [{id, date: filename, size}], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "backups": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_client_store_data/{id}": {
            "get": {
                "operationId": "get_api_get_client_store_data_id",
                "tags": [
                    "Customers"
                ],
                "summary": "Get a customer's store-account credentials",
                "description": "Returns the online-store account linked to a customer: `id` (store-account id), `client_id`, `email` and a `NewPassword: null` placeholder used by the edit form. Errors with 500 if the customer has no store account — check `client_ecommerce` in the list first.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@get_client_store_data",
                "x-source": "app/Http/Controllers/ClientController.php#L420-L431",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "EcommerceClient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id (not the store-account id)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Store-account summary.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                },
                                "example": {
                                    "id": 5,
                                    "client_id": 3,
                                    "email": "jane@acme.test",
                                    "NewPassword": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_clients_without_paginate": {
            "get": {
                "operationId": "get_api_get_clients_without_paginate",
                "tags": [
                    "Customers"
                ],
                "summary": "List all customers (lightweight)",
                "description": "Returns every non-deleted customer as `{id, name, phone}` with no paging. Used to fill customer pickers in POS, sales and quotation forms. No permission check beyond authentication.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@Get_Clients_Without_Paginate",
                "x-source": "app/Http/Controllers/ClientController.php#L411-L416",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Client"
                ],
                "responses": {
                    "200": {
                        "description": "Array of `{id, name, phone}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                },
                                "example": [
                                    {
                                        "id": 1,
                                        "name": "walk-in-customer",
                                        "phone": "0000000000"
                                    },
                                    {
                                        "id": 3,
                                        "name": "ACME Ltd",
                                        "phone": "+212600000000"
                                    }
                                ]
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_config_mail": {
            "get": {
                "operationId": "get_api_get_config_mail",
                "tags": [
                    "Mail Settings"
                ],
                "summary": "Get mail server config",
                "description": "Returns the SMTP configuration row (`servers` table): mailer, host, port, sender name/email, username, password and encryption.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "MailSettingsController@get_config_mail",
                "x-source": "app/Http/Controllers/MailSettingsController.php#L14-L25",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "mail_settings",
                        "slug": "mail_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Server"
                ],
                "responses": {
                    "200": {
                        "description": "`{server: {id, mail_mailer, host, port, sender_name, sender_email, username, password, encryption}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "server": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "500": {
                        "description": "No server row configured.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "statut": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_designations_by_department": {
            "get": {
                "operationId": "get_api_get_designations_by_department",
                "tags": [
                    "Designations"
                ],
                "summary": "Designations of a department",
                "description": "Same as `GET /api/core/get_designations_by_department` — kept for older clients.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\DesignationsController@Get_designations_by_department",
                "x-source": "app/Http/Controllers/hrm/DesignationsController.php#L172-L177",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Designation"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of designations.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_draft_sales": {
            "get": {
                "operationId": "get_api_get_draft_sales",
                "tags": [
                    "POS"
                ],
                "summary": "List held drafts",
                "description": "Paginated draft sales (newest first) scoped to the cashier's warehouses and record view. Rows: `id, date, Ref, warehouse_name, client_name, GrandTotal`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@get_draft_sales",
                "x-source": "app/Http/Controllers/PosController.php#L957-L1022",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "DraftSale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`draft_sales[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "draft_sales": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_emails_template": {
            "get": {
                "operationId": "get_api_get_emails_template",
                "tags": [
                    "Notification Templates"
                ],
                "summary": "Get email templates",
                "description": "Subject and HTML body of every email notification type for one locale (empty strings when not yet customised).",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Notifications_Template@get_emails_template",
                "x-source": "app/Http/Controllers/Notifications_Template.php#L123-L222",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "notification_template",
                        "slug": "notification_template",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "EmailMessage"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Locale code (default `en`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sale: {subject, body}, quotation, payment_received, purchase, payment_sent, booking, asset_validation_due}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sale": {},
                                        "quotation": {},
                                        "payment_received": {},
                                        "purchase": {},
                                        "payment_sent": {},
                                        "booking": {},
                                        "asset_validation_due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_employees_by_department": {
            "get": {
                "operationId": "get_api_get_employees_by_department",
                "tags": [
                    "Employees"
                ],
                "summary": "Employees of a department",
                "description": "`{id, username}` list.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@Get_employees_by_department",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L285-L290",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_experiences_by_employee": {
            "get": {
                "operationId": "get_api_get_experiences_by_employee",
                "tags": [
                    "Employees"
                ],
                "summary": "Work experience of an employee",
                "description": "Paginated experience entries.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@get_experiences_by_employee",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L319-L347",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "view_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "EmployeeExperience"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Employee id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`experiences[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "experiences": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_import_purchases": {
            "get": {
                "operationId": "get_api_get_import_purchases",
                "tags": [
                    "Purchases"
                ],
                "summary": "Get lookups for purchase import",
                "description": "The caller's `warehouses` and all `suppliers`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@get_import_purchases",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2131-L2151",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchases_add",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Provider"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_import_sales": {
            "get": {
                "operationId": "get_api_get_import_sales",
                "tags": [
                    "Sales"
                ],
                "summary": "Get lookups for sale import",
                "description": "`warehouses`, `clients` and `sales_agents` for the *import sale from CSV* screen.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@get_import_sales",
                "x-source": "app/Http/Controllers/SalesController.php#L2061-L2081",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Client",
                    "SalesAgent"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales_agents": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_mobile_settings": {
            "get": {
                "operationId": "get_api_get_mobile_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get mobile-app settings",
                "description": "Every knob on the Mobile App tab: enabled flag, display name, logo (with cache-busted URL), primary colour, theme mode, minimum supported version, maintenance message, enabled modules, offline/scanner/price-edit toggles and support contacts. Missing columns read as `null` and behave like \"not configured\".",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@get_mobile_settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L2188-L2225",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "appearance_settings",
                        "slug": "appearance_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{settings: {mobile_app_enabled, mobile_app_name, mobile_logo, mobile_logo_url, mobile_primary_color, mobile_theme_mode, mobile_min_version, mobile_maintenance_message, mobile_modules, mobile_offline_enabled, mobile_scanner_enabled, mobile_allow_price_edit, mobile_support_phone, mobile_support_email}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "mobile_app_enabled": {
                                                    "type": "boolean"
                                                },
                                                "mobile_app_name": {},
                                                "mobile_logo": {},
                                                "mobile_logo_url": {
                                                    "type": "string"
                                                },
                                                "mobile_primary_color": {},
                                                "mobile_theme_mode": {},
                                                "mobile_min_version": {},
                                                "mobile_maintenance_message": {},
                                                "mobile_modules": {},
                                                "mobile_offline_enabled": {
                                                    "type": "boolean"
                                                },
                                                "mobile_scanner_enabled": {
                                                    "type": "boolean"
                                                },
                                                "mobile_allow_price_edit": {
                                                    "type": "boolean"
                                                },
                                                "mobile_support_phone": {},
                                                "mobile_support_email": {},
                                                "app_name": {},
                                                "default_logo_url": {
                                                    "type": "string"
                                                },
                                                "module_keys": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_modules_info": {
            "get": {
                "operationId": "get_api_get_modules_info",
                "tags": [
                    "Module Settings"
                ],
                "summary": "List installed modules",
                "description": "Every module under `Modules/` with its `module.json` version and enabled status.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "ModuleSettingsController@get_modules_info",
                "x-source": "app/Http/Controllers/ModuleSettingsController.php#L11-L26",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`[{module_name, current_version, status}]`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_payment_gateway": {
            "get": {
                "operationId": "get_api_get_payment_gateway",
                "tags": [
                    "Payment Gateway Settings"
                ],
                "summary": "Get Stripe config",
                "description": "Returns the publishable key; the secret is always blank.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Payment_gateway_SettingsController@Get_payment_gateway",
                "x-source": "app/Http/Controllers/Payment_gateway_SettingsController.php#L13-L24",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "payment_gateway",
                        "slug": "payment_gateway | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{gateway: {stripe_key, stripe_secret: \"\", deleted: false}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "gateway": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_payment_gateway_ws": {
            "get": {
                "operationId": "get_api_get_payment_gateway_ws",
                "tags": [
                    "Payment Gateway Settings"
                ],
                "summary": "Get Stripe config (settings screen)",
                "description": "Same payload as `get_payment_gateway`, guarded by `setting_system`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Payment_gateway_SettingsController@get_payment_gateway_ws",
                "x-source": "app/Http/Controllers/Payment_gateway_SettingsController.php#L26-L37",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{gateway: {...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "gateway": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_payments_by_purchase/{id}": {
            "get": {
                "operationId": "get_api_get_payments_by_purchase_id",
                "tags": [
                    "Purchases"
                ],
                "summary": "List payments of a purchase",
                "description": "All payments made against one purchase (newest first) with payment method, plus the remaining `due`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@Get_Payments",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1070-L1101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_purchases_view",
                        "policy": "PaymentPurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "PaymentPurchase"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `due`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_payments_by_sale/{id}": {
            "get": {
                "operationId": "get_api_get_payments_by_sale_id",
                "tags": [
                    "Sales"
                ],
                "summary": "List payments of a sale",
                "description": "All payments recorded against one sale (newest first) with their payment method, plus the remaining `due`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@Payments_Sale",
                "x-source": "app/Http/Controllers/SalesController.php#L1978-L2010",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_sales_view",
                        "policy": "PaymentSalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "PaymentSale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `due`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_points_client/{id}": {
            "get": {
                "operationId": "get_api_get_points_client_id",
                "tags": [
                    "Customers"
                ],
                "summary": "Get a customer's loyalty points",
                "description": "Returns the current loyalty `points` balance, whether the customer `is_royalty_eligible`, and their name. Used by POS before redeeming points. Returns `404` with `success: false` when the customer does not exist.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@getPoints",
                "x-source": "app/Http/Controllers/ClientController.php#L857-L874",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Points balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "points": {},
                                        "is_royalty_eligible": {},
                                        "name": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "points": 120,
                                    "is_royalty_eligible": 1,
                                    "name": "ACME Ltd"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_pos_Settings": {
            "get": {
                "operationId": "get_api_get_pos_Settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get POS settings (app shell)",
                "description": "Returns the `pos_settings` row for any authenticated user. `allow_overselling` is copied in from the global settings so POS and sale forms can keep reading it here.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@get_pos_Settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L418-L434",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "PosSetting",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{pos_settings: {...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pos_settings": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_pos_Settings_api": {
            "get": {
                "operationId": "get_api_get_pos_Settings_api",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get POS settings (settings screen)",
                "description": "Same as `GET /api/get_pos_Settings` but requires `pos_settings` and adds the global `invoice_format` (`thermal` or `a4`) so the POS Settings page can edit it.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@get_pos_Settings_api",
                "x-source": "app/Http/Controllers/SettingsController.php#L436-L457",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pos_settings",
                        "slug": "pos_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PosSetting",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{pos_settings: {...}, invoice_format}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pos_settings": {},
                                        "invoice_format": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_product_detail/{id}": {
            "get": {
                "operationId": "get_api_get_product_detail_id",
                "tags": [
                    "Products"
                ],
                "summary": "Get product details",
                "description": "Read-only detail view of a product: identity, `type_name` (`Single`/`Variable`/`Service`), category/sub-category names and the multi-category lists, brand, `size_guide`, prices (`price`, `wholesale_price`, `min_price`, `cost`), `taxe` + `tax_method` label, formatted `discount`, warranty/guarantee fields, `is_batch_tracked`, gallery `images`, `packs`, `price_tiers`, and per-warehouse stock in `warehouse[]` (`name`, `qte` — for variants one row per variant). Combo products include `products_combo_data` (component `name`, `code`, `quantity`). Stock rows are restricted to the caller's warehouses.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@Get_Products_Details",
                "x-source": "app/Http/Controllers/ProductsController.php#L1754-L1956",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "products_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "Warehouse",
                    "UserWarehouse",
                    "CombinedProduct",
                    "ProductVariant",
                    "Setting",
                    "ProductPack",
                    "ProductPriceTier"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Product detail object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "quantity": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_product_detail_api/{id}": {
            "get": {
                "operationId": "get_api_get_product_detail_api_id",
                "tags": [
                    "Products"
                ],
                "summary": "Get product details (alias)",
                "description": "Identical to `GET /api/get_product_detail/{id}`; kept for older clients.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@Get_Products_Details",
                "x-source": "app/Http/Controllers/ProductsController.php#L1754-L1956",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "products_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "Warehouse",
                    "UserWarehouse",
                    "CombinedProduct",
                    "ProductVariant",
                    "Setting",
                    "ProductPack",
                    "ProductPriceTier"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Product detail object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "quantity": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_products_materiels": {
            "get": {
                "operationId": "get_api_get_products_materiels",
                "tags": [
                    "Products"
                ],
                "summary": "List single products usable as combo components",
                "description": "All active `is_single` products with `product_id, name, cost, code, unit_name`, for building the `materiels` list of a combo product.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@get_products_materiels",
                "x-source": "app/Http/Controllers/ProductsController.php#L4151-L4162",
                "x-route-name": "get_products_materiels",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Product"
                ],
                "responses": {
                    "200": {
                        "description": "Array of component candidates.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                },
                                "example": [
                                    {
                                        "product_id": 5,
                                        "name": "Cotton T-Shirt",
                                        "cost": 8.5,
                                        "code": "78945612",
                                        "unit_name": "Pc"
                                    }
                                ]
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_products_stock_alerts": {
            "get": {
                "operationId": "get_api_get_products_stock_alerts",
                "tags": [
                    "Products"
                ],
                "summary": "List products at or below their stock alert",
                "description": "Stock-alert report: every stock-managed product/variant whose warehouse quantity is `<=` the product's `stock_alert`, restricted to the caller's warehouses. Rows: `code, name, quantity, warehouse, stock_alert`. `products` is a Laravel paginator object (`data`, `total`, `current_page`, `per_page`, …). `stats` summarises the whole set: `total`, `out_of_stock` (qty ≤ 0), `critical` (qty ≤ 34 % of alert), `warehouses`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@Products_Alert",
                "x-source": "app/Http/Controllers/ProductsController.php#L2527-L2600",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Stock_Alerts",
                        "slug": "Reports_quantity_alerts",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "product_warehouse",
                    "Warehouse",
                    "UserWarehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "name": "warehouse",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Warehouse id to restrict the report to (must be one of the caller's)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`products` (paginator), `warehouses[]`, `stats`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_pwa_settings": {
            "get": {
                "operationId": "get_api_get_pwa_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get PWA settings",
                "description": "Installable-app identity used by every manifest (admin, portal, store, customer display): name, short name, description, start URL, display mode, orientation, theme/background colours, plus current icon URLs with cache-busting query strings. Raw stored values are returned alongside the effective fallbacks so the form can show placeholders.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@get_pwa_settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L2002-L2043",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "appearance_settings",
                        "slug": "appearance_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{settings: {pwa_enabled, pwa_name, pwa_short_name, pwa_description, pwa_start_url, pwa_display, pwa_orientation, pwa_theme_color, pwa_background_color, icon_192_url, icon_512_url, fallbacks...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "pwa_enabled": {
                                                    "type": "boolean"
                                                },
                                                "pwa_name": {},
                                                "pwa_short_name": {},
                                                "pwa_description": {},
                                                "pwa_start_url": {},
                                                "pwa_display": {},
                                                "pwa_orientation": {},
                                                "pwa_theme_color": {},
                                                "pwa_background_color": {},
                                                "app_name": {
                                                    "type": "string"
                                                },
                                                "default_short_name": {
                                                    "type": "string"
                                                },
                                                "default_theme_color": {
                                                    "type": "string",
                                                    "example": "#2f3640"
                                                },
                                                "default_background_color": {
                                                    "type": "string",
                                                    "example": "#ffffff"
                                                },
                                                "icon_192_url": {
                                                    "type": "string"
                                                },
                                                "icon_512_url": {
                                                    "type": "string"
                                                },
                                                "icon_192_exists": {},
                                                "icon_512_exists": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_sms_config": {
            "get": {
                "operationId": "get_api_get_sms_config",
                "tags": [
                    "SMS Settings"
                ],
                "summary": "Get SMS gateway config",
                "description": "Current credentials for every supported gateway (Twilio, Termii, Infobip, custom HTTP) with secrets blanked, the list of available gateways and the default gateway from settings.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Sms_SettingsController@get_sms_config",
                "x-source": "app/Http/Controllers/Sms_SettingsController.php#L14-L63",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "sms_settings",
                        "slug": "sms_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "sms_gateway",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{twilio: {TWILIO_SID, TWILIO_FROM, TWILIO_TOKEN: \"\"}, termi: {...}, infobip: {...}, custom: {...}, sms_gateway: [...], default_sms_gateway}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "twilio": {},
                                        "termi": {},
                                        "infobip": {},
                                        "custom": {},
                                        "sms_gateway": {},
                                        "default_sms_gateway": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_sms_template": {
            "get": {
                "operationId": "get_api_get_sms_template",
                "tags": [
                    "Notification Templates"
                ],
                "summary": "Get SMS templates",
                "description": "Body text of every SMS notification type for one locale.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Notifications_Template@get_sms_template",
                "x-source": "app/Http/Controllers/Notifications_Template.php#L16-L100",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "notification_template",
                        "slug": "notification_template",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "SMSMessage"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Locale code (default `en`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sms_body_sale, sms_body_quotation, sms_body_payment_received, sms_body_purchase, sms_body_payment_sent, sms_body_subscription_reminder, sms_body_asset_validation_due}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sms_body_sale": {},
                                        "sms_body_quotation": {},
                                        "sms_body_payment_received": {},
                                        "sms_body_purchase": {},
                                        "sms_body_payment_sent": {},
                                        "sms_body_subscription_reminder": {},
                                        "sms_body_asset_validation_due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_sub_units_by_base": {
            "get": {
                "operationId": "get_api_get_sub_units_by_base",
                "tags": [
                    "Units"
                ],
                "summary": "List a base unit and its sub-units",
                "description": "Returns the unit `id` plus every unit whose `base_unit` is `id` — the options for a product's sale/purchase unit pickers. Without `id` returns all units.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@Get_Units_SubBase",
                "x-source": "app/Http/Controllers/UnitsController.php#L205-L215",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Unit"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Base unit id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of unit rows.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_today_sales": {
            "get": {
                "operationId": "get_api_get_today_sales",
                "tags": [
                    "Sales"
                ],
                "summary": "Get today's sales summary (POS)",
                "description": "Cashier summary for the POS *Today's sales* panel: `today`, `cashier`, `total_sales_amount`, `total_amount_paid`, and per payment-method totals (`payment_methods[]` with `name`, `amount`). A cashier without record view sees only their own sales and, when they have an open cash register, only the current shift window.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@get_today_sales",
                "x-source": "app/Http/Controllers/SalesController.php#L3832-L3941",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "UserWarehouse",
                    "CashRegister",
                    "Sale",
                    "PaymentMethod",
                    "PaymentSale"
                ],
                "responses": {
                    "200": {
                        "description": "Summary object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_units": {
            "get": {
                "operationId": "get_api_get_units",
                "tags": [
                    "Units"
                ],
                "summary": "List units usable for a product",
                "description": "Given a product `id`, returns the product's base unit and all of its sub-units (the units a document line can be expressed in).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@Get_sales_units",
                "x-source": "app/Http/Controllers/UnitsController.php#L219-L233",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Product",
                    "Unit"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of unit rows.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_user_auth": {
            "get": {
                "operationId": "get_api_get_user_auth",
                "tags": [
                    "Users"
                ],
                "summary": "Get the logged-in user, settings and permissions",
                "description": "Boot payload for the admin SPA. Returns:\n\n- `user` – id, avatar, username plus the global UI settings the front-end needs (currency, `enable_multi_currency`, `default_currency_id`, logo, `default_language`, footer, `app_name`, `date_format`, `price_format`, `price_decimals` (2 or 3), `dark_mode`, `enable_kitchen_display`, `timezone`, `sidebar_menu_order`, `module_flags`, `export_settings`, …)\n- `permissions` – array of permission slugs granted by the user's role (e.g. `Customers_view`)\n- `notifs` – number of products at or below their stock alert level",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@GetUserAuth",
                "x-source": "app/Http/Controllers/UserController.php#L88-L153",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Setting",
                    "product_warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "Boot payload.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "user": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "notifs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "permissions": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "user": {
                                        "id": 1,
                                        "username": "William Castillo",
                                        "avatar": "no_avatar.png",
                                        "currency": {
                                            "symbol": "$",
                                            "code": "USD"
                                        },
                                        "default_language": "en",
                                        "date_format": "YYYY-MM-DD",
                                        "price_decimals": 2,
                                        "dark_mode": false,
                                        "module_flags": null
                                    },
                                    "permissions": [
                                        "Customers_view",
                                        "Sales_add"
                                    ],
                                    "notifs": 3
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/get_version_info": {
            "get": {
                "operationId": "get_api_get_version_info",
                "tags": [
                    "System Update"
                ],
                "summary": "Get version info",
                "description": "Reads the installed version from `version.txt`, fetches the latest release metadata from the vendor update server (10 s timeout, failure tolerated) and returns the changelog and local update history.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "UpdateController@get_version_info",
                "x-source": "app/Http/Controllers/UpdateController.php#L18-L74",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`{current_version, latest_version, latest_info, changelog: [], update_history: []}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "type": {
                                            "type": "string",
                                            "example": "misc"
                                        },
                                        "text": {},
                                        "current_version": {},
                                        "latest_version": {},
                                        "latest_info": {},
                                        "changelog": {},
                                        "update_history": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/create-spreadsheet": {
            "post": {
                "operationId": "post_api_google_sheets_create_spreadsheet",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Create a new spreadsheet",
                "description": "Creates a spreadsheet in the connected Drive and stores its id.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@createSpreadsheet",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L120-L130",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Spreadsheet info.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/disconnect": {
            "post": {
                "operationId": "post_api_google_sheets_disconnect",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Disconnect Google account",
                "description": "Drop the token pair; app credentials and spreadsheet stay.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@disconnect",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L86-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "x-models": [
                    "GoogleSheetSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/export/customers": {
            "post": {
                "operationId": "post_api_google_sheets_export_customers",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Export customers",
                "description": "Pushes the customer list to the configured Google Sheet (creates or replaces the `Customers` tab). Runs synchronously and logs the result.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@exportCustomers",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L149-L152",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call.",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `exported`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/export/products": {
            "post": {
                "operationId": "post_api_google_sheets_export_products",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Export products",
                "description": "Pushes the product list (code, name, category, price, cost, stock per warehouse) to the configured Google Sheet.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@exportProducts",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L144-L147",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call.",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `exported`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/export/sales": {
            "post": {
                "operationId": "post_api_google_sheets_export_sales",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Export sales",
                "description": "Batched: call repeatedly passing the returned `last_id` as `start_after_id` until `done`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@exportSales",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L139-L142",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call.",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `exported`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/logs": {
            "delete": {
                "operationId": "delete_api_google_sheets_logs",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Clear export logs",
                "description": "Clears the export log.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@clearLogs",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L181-L188",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "x-models": [
                    "GoogleSheetLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_google_sheets_logs",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Export logs",
                "description": "Paginated export log entries with type, status, rows exported and message.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@logs",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L169-L179",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "GoogleSheetLog"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`info`, `warning`, `error`."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 20)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/settings": {
            "get": {
                "operationId": "get_api_google_sheets_settings",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Get Google Sheets settings",
                "description": "Current Google Sheets integration settings (spreadsheet ID, sheet names, enabled flag); the service-account key is masked.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@settings",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L19-L37",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "x-models": [
                    "GoogleSheetSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `connected`, `client_id`, `has_client_secret`, `spreadsheet_id`, `spreadsheet_url`, `auto_export`, `last_sync_at`, `connect_url`, `callback_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "connected": {},
                                        "client_id": {},
                                        "has_client_secret": {},
                                        "spreadsheet_id": {},
                                        "spreadsheet_url": {},
                                        "auto_export": {
                                            "type": "boolean"
                                        },
                                        "last_sync_at": {
                                            "type": "string"
                                        },
                                        "connect_url": {
                                            "type": "string"
                                        },
                                        "callback_url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_google_sheets_settings",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Save Google Sheets settings",
                "description": "Saves the spreadsheet ID, tab names, enabled flag and the service-account JSON key used to authenticate.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@saveSettings",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L39-L69",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "x-models": [
                    "GoogleSheetSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "auto_export": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Export automatically on changes."
                                    },
                                    "client_id": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "OAuth client id."
                                    },
                                    "client_secret": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "OAuth client secret (write-only)."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "spreadsheet": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Spreadsheet id or URL."
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `spreadsheet_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "spreadsheet_id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/stats": {
            "get": {
                "operationId": "get_api_google_sheets_stats",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Export statistics",
                "description": "Counters for the dashboard card: last export dates and row counts per entity.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@stats",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L132-L137",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Counts per entity and last export times.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/google-sheets/test-connection": {
            "post": {
                "operationId": "post_api_google_sheets_test_connection",
                "tags": [
                    "Google Sheets"
                ],
                "summary": "Test the Google connection",
                "description": "Authenticates with the stored credentials and reads the spreadsheet title. Returns `success` and a message.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\GoogleSheetsSyncController@testConnection",
                "x-source": "app/Http/Controllers/Integrations/GoogleSheetsSyncController.php#L103-L118",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "GoogleSheetSettingPolicy"
                    }
                ],
                "x-models": [
                    "GoogleSheetSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not connected / failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Not connected"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/holiday": {
            "get": {
                "operationId": "get_api_holiday",
                "tags": [
                    "Holidays"
                ],
                "summary": "List holidays",
                "description": "Paginated rows `id, title, company_id, company_name, start_date, end_date, description`. `search` matches the title.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@index",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L15-L61",
                "x-route-name": "holiday.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Holiday"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`holidays[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "holidays": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_holiday",
                "tags": [
                    "Holidays"
                ],
                "summary": "Create a holiday",
                "description": "Creates a company holiday (title, start/end date, optional description). Holidays are excluded from attendance and payroll working days.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@store",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L76-L96",
                "x-route-name": "holiday.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-models": [
                    "Holiday"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last day."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First day."
                                    },
                                    "title": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "end_date",
                                    "start_date",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/holiday/create": {
            "get": {
                "operationId": "get_api_holiday_create",
                "tags": [
                    "Holidays"
                ],
                "summary": "Create-form data for a holiday",
                "description": "Lookup data for the holiday form (companies).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@create",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L63-L72",
                "x-route-name": "holiday.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/holiday/delete/by_selection": {
            "post": {
                "operationId": "post_api_holiday_delete_by_selection",
                "tags": [
                    "Holidays"
                ],
                "summary": "Delete selected holidays",
                "description": "Bulk soft-delete of holidays by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L157-L170",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-models": [
                    "Holiday"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Holiday ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/holiday/{holiday}": {
            "delete": {
                "operationId": "delete_api_holiday_holiday",
                "tags": [
                    "Holidays"
                ],
                "summary": "Delete a holiday",
                "description": "Soft-deletes a holiday.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@destroy",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L144-L153",
                "x-route-name": "holiday.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-models": [
                    "Holiday"
                ],
                "parameters": [
                    {
                        "name": "holiday",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Holiday id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_holiday_holiday",
                "tags": [
                    "Holidays"
                ],
                "summary": "Get a holiday (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@show",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L100-L104",
                "x-route-name": "holiday.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "holiday",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Holiday id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_holiday_holiday",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Holidays"
                ],
                "summary": "Update a holiday",
                "description": "Updates a holiday with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@update",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L120-L140",
                "x-route-name": "holiday.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-models": [
                    "Holiday"
                ],
                "parameters": [
                    {
                        "name": "holiday",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Holiday id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last day."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First day."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 255)."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "end_date",
                                    "start_date",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_holiday_holiday",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Holidays"
                ],
                "summary": "Update a holiday",
                "description": "Updates a holiday with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@update",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L120-L140",
                "x-route-name": "holiday.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-models": [
                    "Holiday"
                ],
                "parameters": [
                    {
                        "name": "holiday",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Holiday id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last day."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First day."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 255)."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "end_date",
                                    "start_date",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/holiday/{holiday}/edit": {
            "get": {
                "operationId": "get_api_holiday_holiday_edit",
                "tags": [
                    "Holidays"
                ],
                "summary": "Edit-form data for a holiday",
                "description": "The holiday with the lookups needed by the edit form.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\HolidayController@edit",
                "x-source": "app/Http/Controllers/hrm/HolidayController.php#L106-L116",
                "x-route-name": "holiday.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "holiday",
                        "policy": "HolidayPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "holiday",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Holiday id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/admissions": {
            "get": {
                "operationId": "get_api_hospital_admissions",
                "tags": [
                    "Hospital: Admissions"
                ],
                "summary": "List admissions",
                "description": "Paginated in-patient admissions with patient, ward/bed, doctor, admitted/discharged dates and status. Filter by `status`, `ward_id`, `doctor_id`, `patient_id` or date range.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAdmissionController@index",
                "x-source": "app/Http/Controllers/HospitalAdmissionController.php#L24-L75",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "AdmissionPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Admission"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "doctor_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Doctor."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Admitted to."
                    },
                    {
                        "name": "patient_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Patient."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Admitted from."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`admitted`, `discharged`, `transferred`, `deceased`."
                    },
                    {
                        "name": "ward_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Ward."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`admissions[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "admissions": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_admissions",
                "tags": [
                    "Hospital: Admissions"
                ],
                "summary": "Admit a patient",
                "description": "Occupies the bed and generates an `ADM-…` reference. Refused if the patient is already admitted or the bed is not available.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAdmissionController@store",
                "x-source": "app/Http/Controllers/HospitalAdmissionController.php#L77-L124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "AdmissionPolicy"
                    }
                ],
                "x-models": [
                    "Admission"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "admitted_at": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admission date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "bed_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "hospital_beds,id",
                                        "x-conditional": [
                                            "nullable",
                                            "required"
                                        ],
                                        "x-laravel-rules": [
                                            "exists:hospital_beds,id",
                                            "conditional:nullable",
                                            "conditional:required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Bed to occupy."
                                    },
                                    "daily_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Bed rate override."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "diagnosis": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Diagnosis."
                                    },
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Attending doctor."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason."
                                    }
                                },
                                "required": [
                                    "admitted_at",
                                    "patient_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient_id": {},
                                        "doctor_id": {},
                                        "bed_id": {},
                                        "department_id": {},
                                        "admitted_at": {},
                                        "daily_rate": {},
                                        "reason": {},
                                        "diagnosis": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/admissions/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_admissions_id",
                "tags": [
                    "Hospital: Admissions"
                ],
                "summary": "Delete an admission",
                "description": "Frees the bed when the admission was open.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAdmissionController@destroy",
                "x-source": "app/Http/Controllers/HospitalAdmissionController.php#L221-L238",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AdmissionPolicy"
                    }
                ],
                "x-models": [
                    "Admission",
                    "HospitalBed"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Admission id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_admissions_id",
                "tags": [
                    "Hospital: Admissions"
                ],
                "summary": "Update admission details",
                "description": "Clinical details only; move beds with *Transfer*.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAdmissionController@update",
                "x-source": "app/Http/Controllers/HospitalAdmissionController.php#L127-L139",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AdmissionPolicy"
                    }
                ],
                "x-models": [
                    "Admission"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Admission id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "admitted_at": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admission date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "bed_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "hospital_beds,id",
                                        "x-conditional": [
                                            "nullable",
                                            "required"
                                        ],
                                        "x-laravel-rules": [
                                            "exists:hospital_beds,id",
                                            "conditional:nullable",
                                            "conditional:required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Bed to occupy."
                                    },
                                    "daily_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Bed rate override."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "diagnosis": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Diagnosis."
                                    },
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Attending doctor."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason."
                                    }
                                },
                                "required": [
                                    "admitted_at",
                                    "patient_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient_id": {},
                                        "doctor_id": {},
                                        "bed_id": {},
                                        "department_id": {},
                                        "admitted_at": {},
                                        "daily_rate": {},
                                        "reason": {},
                                        "diagnosis": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/admissions/{id}/discharge": {
            "post": {
                "operationId": "post_api_hospital_admissions_id_discharge",
                "tags": [
                    "Hospital: Admissions"
                ],
                "summary": "Discharge",
                "description": "Closes the stay, frees the bed and returns the computed `nights` and `bed_charge`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAdmissionController@discharge",
                "x-source": "app/Http/Controllers/HospitalAdmissionController.php#L141-L175",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AdmissionPolicy"
                    }
                ],
                "x-models": [
                    "Admission",
                    "HospitalBed"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Admission id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "discharge_summary": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Summary."
                                    },
                                    "discharged_at": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Discharge date-time (default now).",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "discharged",
                                            "transferred",
                                            "deceased"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:discharged,transferred,deceased"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`discharged` (default), `transferred`, `deceased`."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success`, `nights`, `bed_charge`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "nights": {},
                                        "bed_charge": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/admissions/{id}/transfer": {
            "post": {
                "operationId": "post_api_hospital_admissions_id_transfer",
                "tags": [
                    "Hospital: Admissions"
                ],
                "summary": "Transfer to another bed",
                "description": "Move an admitted patient to another bed, freeing the old one.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAdmissionController@transfer",
                "x-source": "app/Http/Controllers/HospitalAdmissionController.php#L178-L219",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AdmissionPolicy"
                    }
                ],
                "x-models": [
                    "Admission",
                    "HospitalBed"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Admission id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "bed_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "hospital_beds,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:hospital_beds,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Destination bed."
                                    },
                                    "daily_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New rate."
                                    }
                                },
                                "required": [
                                    "bed_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/appointments": {
            "get": {
                "operationId": "get_api_hospital_appointments",
                "tags": [
                    "Hospital: Appointments"
                ],
                "summary": "List appointments",
                "description": "Paginated appointments with patient, doctor, department, scheduled time, type and status. Filter by `doctor_id`, `patient_id`, `status`, `date`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAppointmentController@index",
                "x-source": "app/Http/Controllers/HospitalAppointmentController.php#L21-L78",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "AppointmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Appointment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    },
                    {
                        "name": "doctor_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Doctor."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "patient_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Patient."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "today",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = today only."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Type."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`appointments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "appointments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_appointments",
                "tags": [
                    "Hospital: Appointments"
                ],
                "summary": "Book an appointment",
                "description": "Generates an `APT-…` reference; `fee` defaults to the doctor's consultation fee. Refused on a time clash.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAppointmentController@store",
                "x-source": "app/Http/Controllers/HospitalAppointmentController.php#L80-L105",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "AppointmentPolicy"
                    }
                ],
                "x-models": [
                    "Appointment",
                    "Doctor"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Doctor."
                                    },
                                    "duration_minutes": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 480,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:5",
                                            "max:480"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Duration (5–480)."
                                    },
                                    "fee": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Fee."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason for visit."
                                    },
                                    "scheduled_at": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "confirmed",
                                            "arrived",
                                            "completed",
                                            "cancelled",
                                            "no_show"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:scheduled,confirmed,arrived,completed,cancelled,no_show"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "consultation",
                                            "follow_up",
                                            "procedure",
                                            "emergency",
                                            "teleconsult"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:consultation,follow_up,procedure,emergency,teleconsult"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    }
                                },
                                "required": [
                                    "doctor_id",
                                    "patient_id",
                                    "scheduled_at",
                                    "status",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient_id": {},
                                        "doctor_id": {},
                                        "department_id": {},
                                        "scheduled_at": {},
                                        "duration_minutes": {},
                                        "type": {},
                                        "status": {},
                                        "reason": {},
                                        "fee": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/appointments/board": {
            "get": {
                "operationId": "get_api_hospital_appointments_board",
                "tags": [
                    "Hospital: Appointments"
                ],
                "summary": "Day board",
                "description": "One column per active doctor with working hours and the day's appointments.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAppointmentController@board",
                "x-source": "app/Http/Controllers/HospitalAppointmentController.php#L158-L190",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "AppointmentPolicy"
                    }
                ],
                "x-models": [
                    "Doctor",
                    "Appointment"
                ],
                "parameters": [
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date (default today)."
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`date` and `columns[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "date": {
                                            "type": "string"
                                        },
                                        "columns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "doctor_id": {},
                                        "doctor_name": {},
                                        "specialty": {},
                                        "working": {},
                                        "hours": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "appointments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/appointments/delete/by_selection": {
            "post": {
                "operationId": "post_api_hospital_appointments_delete_by_selection",
                "tags": [
                    "Hospital: Appointments"
                ],
                "summary": "Delete selected appointments",
                "description": "Bulk delete of appointments by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAppointmentController@deleteBySelection",
                "x-source": "app/Http/Controllers/HospitalAppointmentController.php#L147-L155",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AppointmentPolicy"
                    }
                ],
                "x-models": [
                    "Appointment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Appointment ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/appointments/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_appointments_id",
                "tags": [
                    "Hospital: Appointments"
                ],
                "summary": "Delete an appointment",
                "description": "Deletes an appointment. Appointments already converted to a visit cannot be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAppointmentController@destroy",
                "x-source": "app/Http/Controllers/HospitalAppointmentController.php#L138-L145",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "AppointmentPolicy"
                    }
                ],
                "x-models": [
                    "Appointment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Appointment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_appointments_id",
                "tags": [
                    "Hospital: Appointments"
                ],
                "summary": "Update an appointment",
                "description": "Reschedules or updates an appointment with the same fields as creation. Changing `status` to `completed` or `cancelled` records the time.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAppointmentController@update",
                "x-source": "app/Http/Controllers/HospitalAppointmentController.php#L107-L123",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AppointmentPolicy"
                    }
                ],
                "x-models": [
                    "Appointment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Appointment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Doctor."
                                    },
                                    "duration_minutes": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 480,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:5",
                                            "max:480"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Duration (5–480)."
                                    },
                                    "fee": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Fee."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason for visit."
                                    },
                                    "scheduled_at": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "confirmed",
                                            "arrived",
                                            "completed",
                                            "cancelled",
                                            "no_show"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:scheduled,confirmed,arrived,completed,cancelled,no_show"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "consultation",
                                            "follow_up",
                                            "procedure",
                                            "emergency",
                                            "teleconsult"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:consultation,follow_up,procedure,emergency,teleconsult"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    }
                                },
                                "required": [
                                    "doctor_id",
                                    "patient_id",
                                    "scheduled_at",
                                    "status",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient_id": {},
                                        "doctor_id": {},
                                        "department_id": {},
                                        "scheduled_at": {},
                                        "duration_minutes": {},
                                        "type": {},
                                        "status": {},
                                        "reason": {},
                                        "fee": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/appointments/{id}/status": {
            "post": {
                "operationId": "post_api_hospital_appointments_id_status",
                "tags": [
                    "Hospital: Appointments"
                ],
                "summary": "Change appointment status",
                "description": "Quick status change from the list (arrived, completed, cancelled...).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalAppointmentController@setStatus",
                "x-source": "app/Http/Controllers/HospitalAppointmentController.php#L126-L136",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "AppointmentPolicy"
                    }
                ],
                "x-models": [
                    "Appointment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Appointment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "confirmed",
                                            "arrived",
                                            "completed",
                                            "cancelled",
                                            "no_show"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:scheduled,confirmed,arrived,completed,cancelled,no_show"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New status."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/available-beds": {
            "get": {
                "operationId": "get_api_hospital_available_beds",
                "tags": [
                    "Hospital: Dashboard"
                ],
                "summary": "Free beds",
                "description": "Free beds for the admission form, grouped by ward.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDashboardController@availableBeds",
                "x-source": "app/Http/Controllers/HospitalDashboardController.php#L214-L233",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "AdmissionPolicy"
                    }
                ],
                "x-models": [
                    "HospitalBed"
                ],
                "parameters": [
                    {
                        "name": "ward_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Ward filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`beds[] {id, bed_number, ward_id, ward_name, daily_rate, label}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "beds": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/beds": {
            "get": {
                "operationId": "get_api_hospital_beds",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "Bed board",
                "description": "Every bed grouped by ward with the current occupant.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@beds",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L120-L168",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-models": [
                    "HospitalWard",
                    "HospitalBed",
                    "Admission"
                ],
                "parameters": [
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    },
                    {
                        "name": "ward_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Ward."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`wards[] {…, beds[] {bed_number, status, admission_id, patient_name, admitted_at}}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "wards": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "id": {},
                                        "name": {},
                                        "type": {},
                                        "floor": {},
                                        "department_name": {},
                                        "daily_rate": {},
                                        "beds": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "bed_number": {},
                                        "status": {},
                                        "notes": {},
                                        "admission_id": {},
                                        "patient_id": {},
                                        "patient_name": {},
                                        "admitted_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_beds",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "Add beds",
                "description": "`bed_number` accepts a range (`A1-A10`) to create several beds at once; existing numbers are skipped.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@storeBed",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L170-L200",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-models": [
                    "HospitalBed"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "bed_number": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "x-conditional": [
                                            "nullable",
                                            "required"
                                        ],
                                        "x-laravel-rules": [
                                            "string",
                                            "max:40",
                                            "conditional:nullable",
                                            "conditional:required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Number or range."
                                    },
                                    "daily_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rate override."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "occupied",
                                            "maintenance",
                                            "reserved"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:available,occupied,maintenance,reserved"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`available`, `maintenance`, `reserved`."
                                    },
                                    "ward_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "hospital_wards,id",
                                        "x-conditional": [
                                            "nullable",
                                            "required"
                                        ],
                                        "x-laravel-rules": [
                                            "exists:hospital_wards,id",
                                            "conditional:nullable",
                                            "conditional:required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Ward."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/beds/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_beds_id",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "Delete a bed",
                "description": "Deletes a bed. Occupied beds cannot be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@destroyBed",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L233-L247",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-models": [
                    "HospitalBed"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Bed id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Bed occupied.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This bed is occupied. Discharge or transfer the patient first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_beds_id",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "Update a bed",
                "description": "`occupied` cannot be set or cleared here.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@updateBed",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L202-L231",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-models": [
                    "HospitalBed"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Bed id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "bed_number": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "x-conditional": [
                                            "nullable",
                                            "required"
                                        ],
                                        "x-laravel-rules": [
                                            "string",
                                            "max:40",
                                            "conditional:nullable",
                                            "conditional:required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Number."
                                    },
                                    "daily_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rate."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "occupied",
                                            "maintenance",
                                            "reserved"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:available,occupied,maintenance,reserved"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "ward_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "hospital_wards,id",
                                        "x-conditional": [
                                            "nullable",
                                            "required"
                                        ],
                                        "x-laravel-rules": [
                                            "exists:hospital_wards,id",
                                            "conditional:nullable",
                                            "conditional:required"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Ward."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/dashboard": {
            "get": {
                "operationId": "get_api_hospital_dashboard",
                "tags": [
                    "Hospital: Dashboard"
                ],
                "summary": "Hospital dashboard",
                "description": "Census (patients, doctors, departments), today's appointments / visits / admissions / discharges, bed occupancy, pending and critical lab orders, revenue today / month, outstanding, trends and ward occupancy.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDashboardController@dashboard",
                "x-source": "app/Http/Controllers/HospitalDashboardController.php#L31-L96",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "dashboard",
                        "slug": "hms_dashboard",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "HospitalBed",
                    "Patient",
                    "Doctor",
                    "HospitalDepartment",
                    "Appointment",
                    "PatientVisit",
                    "Admission",
                    "LabOrder",
                    "HospitalPayment",
                    "HospitalInvoice"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patients_total": {
                                            "type": "integer"
                                        },
                                        "patients_new_today": {
                                            "type": "integer"
                                        },
                                        "doctors_active": {
                                            "type": "integer"
                                        },
                                        "departments": {
                                            "type": "integer"
                                        },
                                        "appointments_today": {
                                            "type": "integer"
                                        },
                                        "appointments_pending": {
                                            "type": "integer"
                                        },
                                        "visits_today": {
                                            "type": "integer"
                                        },
                                        "admissions_current": {
                                            "type": "integer"
                                        },
                                        "admissions_today": {
                                            "type": "integer"
                                        },
                                        "discharges_today": {
                                            "type": "integer"
                                        },
                                        "beds_total": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "beds_occupied": {},
                                        "beds_available": {
                                            "type": "integer"
                                        },
                                        "occupancy_rate": {
                                            "type": "number"
                                        },
                                        "lab_pending": {
                                            "type": "integer"
                                        },
                                        "lab_critical": {
                                            "type": "integer"
                                        },
                                        "revenue_today": {
                                            "type": "number"
                                        },
                                        "revenue_month": {
                                            "type": "number"
                                        },
                                        "outstanding": {
                                            "type": "number"
                                        },
                                        "trend": {},
                                        "by_department": {},
                                        "upcoming": {},
                                        "ward_occupancy": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/departments": {
            "get": {
                "operationId": "get_api_hospital_departments",
                "tags": [
                    "Hospital: Departments"
                ],
                "summary": "List departments",
                "description": "With doctor and ward counts.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDepartmentController@index",
                "x-source": "app/Http/Controllers/HospitalDepartmentController.php#L20-L73",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "HospitalDepartmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "HospitalDepartment",
                    "Doctor",
                    "HospitalWard"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` / `0`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`departments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "departments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_departments",
                "tags": [
                    "Hospital: Departments"
                ],
                "summary": "Create a department",
                "description": "Creates a hospital department (name, code, head doctor, description).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDepartmentController@store",
                "x-source": "app/Http/Controllers/HospitalDepartmentController.php#L75-L83",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "HospitalDepartmentPolicy"
                    }
                ],
                "x-models": [
                    "HospitalDepartment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location / floor."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "description": {},
                                        "location": {},
                                        "phone": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/departments/delete/by_selection": {
            "post": {
                "operationId": "post_api_hospital_departments_delete_by_selection",
                "tags": [
                    "Hospital: Departments"
                ],
                "summary": "Delete selected departments",
                "description": "Bulk delete of departments by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDepartmentController@deleteBySelection",
                "x-source": "app/Http/Controllers/HospitalDepartmentController.php#L111-L121",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "HospitalDepartmentPolicy"
                    }
                ],
                "x-models": [
                    "Doctor",
                    "HospitalWard",
                    "HospitalDepartment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Department ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/departments/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_departments_id",
                "tags": [
                    "Hospital: Departments"
                ],
                "summary": "Delete a department",
                "description": "Doctors and wards are detached rather than deleted — losing a department must never quietly remove the practitioners inside it. /",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDepartmentController@destroy",
                "x-source": "app/Http/Controllers/HospitalDepartmentController.php#L99-L109",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "HospitalDepartmentPolicy"
                    }
                ],
                "x-models": [
                    "HospitalDepartment",
                    "Doctor",
                    "HospitalWard"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Department id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_departments_id",
                "tags": [
                    "Hospital: Departments"
                ],
                "summary": "Update a department",
                "description": "Updates a department with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDepartmentController@update",
                "x-source": "app/Http/Controllers/HospitalDepartmentController.php#L85-L93",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "HospitalDepartmentPolicy"
                    }
                ],
                "x-models": [
                    "HospitalDepartment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Department id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "description": {},
                                        "location": {},
                                        "phone": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/doctors": {
            "get": {
                "operationId": "get_api_hospital_doctors",
                "tags": [
                    "Hospital: Doctors"
                ],
                "summary": "List doctors",
                "description": "Paginated doctors with department, specialty, consultation fee and active flag. Filter by `department_id`, `specialty`, `active`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDoctorController@index",
                "x-source": "app/Http/Controllers/HospitalDoctorController.php#L27-L76",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "DoctorPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Doctor",
                    "Appointment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` / `0`."
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`doctors[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "doctors": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_doctors",
                "tags": [
                    "Hospital: Doctors"
                ],
                "summary": "Create a doctor",
                "description": "Multipart. `availability` is a JSON object keyed by weekday (`mon`..`sun`) with `from` / `to` hours.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDoctorController@store",
                "x-source": "app/Http/Controllers/HospitalDoctorController.php#L87-L98",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "DoctorPolicy"
                    }
                ],
                "x-models": [
                    "Doctor"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "availability": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Weekly availability JSON.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Staff code."
                                    },
                                    "consultation_fee": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default fee."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked HR employee."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "license_no": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Licence number."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "qualification": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Qualification."
                                    },
                                    "specialty": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Specialty."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "department_id": {},
                                        "employee_id": {},
                                        "specialty": {},
                                        "qualification": {},
                                        "license_no": {},
                                        "phone": {},
                                        "email": {},
                                        "consultation_fee": {},
                                        "availability": {},
                                        "is_active": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/doctors/delete/by_selection": {
            "post": {
                "operationId": "post_api_hospital_doctors_delete_by_selection",
                "tags": [
                    "Hospital: Doctors"
                ],
                "summary": "Delete selected doctors",
                "description": "Bulk soft-delete of doctors by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDoctorController@deleteBySelection",
                "x-source": "app/Http/Controllers/HospitalDoctorController.php#L131-L139",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "DoctorPolicy"
                    }
                ],
                "x-models": [
                    "Doctor"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Doctor ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/doctors/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_doctors_id",
                "tags": [
                    "Hospital: Doctors"
                ],
                "summary": "Delete a doctor",
                "description": "Soft-deletes a doctor; their appointments and visits are kept.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDoctorController@destroy",
                "x-source": "app/Http/Controllers/HospitalDoctorController.php#L122-L129",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "DoctorPolicy"
                    }
                ],
                "x-models": [
                    "Doctor"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Doctor id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_hospital_doctors_id",
                "tags": [
                    "Hospital: Doctors"
                ],
                "summary": "Get a doctor",
                "description": "One doctor with department, availability schedule and recent appointment statistics.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDoctorController@show",
                "x-source": "app/Http/Controllers/HospitalDoctorController.php#L78-L85",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "DoctorPolicy"
                    }
                ],
                "x-models": [
                    "Doctor"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Doctor id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`doctor`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "doctor": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/doctors/{id}/schedule": {
            "get": {
                "operationId": "get_api_hospital_doctors_id_schedule",
                "tags": [
                    "Hospital: Doctors"
                ],
                "summary": "Doctor's diary for a day",
                "description": "The doctor's diary for one day, used by the appointment booker.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDoctorController@schedule",
                "x-source": "app/Http/Controllers/HospitalDoctorController.php#L142-L172",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "DoctorPolicy"
                    }
                ],
                "x-models": [
                    "Doctor",
                    "Appointment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Doctor id."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date (default today)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`date`, `working`, `hours`, `appointments[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "date": {
                                            "type": "string"
                                        },
                                        "working": {},
                                        "hours": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "appointments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/doctors/{id}/update": {
            "post": {
                "operationId": "post_api_hospital_doctors_id_update",
                "tags": [
                    "Hospital: Doctors"
                ],
                "summary": "Update a doctor",
                "description": "Updates a doctor with the same fields as creation (multipart; send `image` to replace the photo).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDoctorController@update",
                "x-source": "app/Http/Controllers/HospitalDoctorController.php#L100-L120",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "DoctorPolicy"
                    }
                ],
                "x-models": [
                    "Doctor"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Doctor id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "availability": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Weekly availability JSON.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Staff code."
                                    },
                                    "consultation_fee": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default fee."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked HR employee."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "license_no": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Licence number."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "qualification": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Qualification."
                                    },
                                    "remove_image": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remove photo.",
                                        "type": "boolean"
                                    },
                                    "specialty": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Specialty."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "department_id": {},
                                        "employee_id": {},
                                        "specialty": {},
                                        "qualification": {},
                                        "license_no": {},
                                        "phone": {},
                                        "email": {},
                                        "consultation_fee": {},
                                        "availability": {},
                                        "is_active": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/invoices": {
            "get": {
                "operationId": "get_api_hospital_invoices",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "List invoices",
                "description": "Paginated with `totals` (billed, paid, due).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@index",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L30-L84",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "HospitalInvoice"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "outstanding",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = unpaid / partial only."
                    },
                    {
                        "name": "patient_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Patient."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`invoices[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "invoices": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_invoices",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "Create an invoice",
                "description": "Generates an `INV-…` reference; totals are computed from the items.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@store",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L114-L145",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-models": [
                    "HospitalInvoice"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "admission_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "admissions,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:admissions,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admission."
                                    },
                                    "discount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Discount amount."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "invoice_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {},
                                        "description": "`[{type: consultation|medicine|lab|bed|other, product_id?, description, quantity, unit_price}]`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "lab_order_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "lab_orders,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:lab_orders,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Lab order."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "unpaid",
                                            "partial",
                                            "paid",
                                            "cancelled"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:draft,unpaid,partial,paid,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status (default `unpaid`)."
                                    },
                                    "tax": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "visit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "patient_visits,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:patient_visits,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Visit."
                                    }
                                },
                                "required": [
                                    "items",
                                    "patient_id",
                                    "items"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/invoices/draft-from": {
            "post": {
                "operationId": "post_api_hospital_invoices_draft_from",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "Draft lines from a visit, admission or lab order",
                "description": "Returns pre-priced lines (consultation fee, prescribed medicines, tests, bed nights) to paste into *Create an invoice*.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@draftFrom",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L320-L376",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-models": [
                    "PatientVisit",
                    "Prescription",
                    "Admission",
                    "LabOrder"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source record id."
                                    },
                                    "source": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "visit",
                                            "admission",
                                            "lab_order"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:visit,admission,lab_order"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`visit`, `admission` or `lab_order`."
                                    }
                                },
                                "required": [
                                    "id",
                                    "source"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`draft {patient_id, visit_id, admission_id, lab_order_id, items[]}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "draft": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/invoices/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_invoices_id",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "Delete an invoice",
                "description": "Deletes a hospital invoice and its payments. Paid invoices cannot be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@destroy",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L172-L190",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-models": [
                    "HospitalInvoice",
                    "HospitalInvoiceItem"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Has payments.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This invoice has payments recorded against it. Reverse those first, or cancel the invoice instead."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_hospital_invoices_id",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "Get an invoice",
                "description": "One invoice with patient, linked visit/admission/lab order, line items, tax, discount, payments and balance.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@show",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L86-L112",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-models": [
                    "HospitalInvoice"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`invoice` with `items[]` and `payments[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "invoice": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_invoices_id",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "Update an invoice",
                "description": "Replaces the lines and recomputes totals.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@update",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L147-L170",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-models": [
                    "HospitalInvoice"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "admission_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "admissions,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:admissions,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Admission."
                                    },
                                    "discount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Discount amount."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "invoice_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {},
                                        "description": "Lines (full replacement).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "lab_order_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "lab_orders,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:lab_orders,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Lab order."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "unpaid",
                                            "partial",
                                            "paid",
                                            "cancelled"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:draft,unpaid,partial,paid,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status (default `unpaid`)."
                                    },
                                    "tax": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "visit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "patient_visits,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:patient_visits,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Visit."
                                    }
                                },
                                "required": [
                                    "items",
                                    "patient_id",
                                    "items"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/invoices/{id}/payments": {
            "post": {
                "operationId": "post_api_hospital_invoices_id_payments",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "Record a payment",
                "description": "Refused on cancelled invoices and when the amount exceeds the balance due.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@storePayment",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L196-L237",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-models": [
                    "HospitalInvoice",
                    "HospitalPayment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount."
                                    },
                                    "method": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Method (cash, card, insurance…)."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "paid_on": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    }
                                },
                                "required": [
                                    "amount"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and remaining `due`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/invoices/{invoiceId}/payments/{paymentId}": {
            "delete": {
                "operationId": "delete_api_hospital_invoices_invoiceId_payments_paymentId",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "Delete a payment",
                "description": "Deletes a payment and recomputes the invoice balance and status.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@destroyPayment",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L239-L252",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-models": [
                    "HospitalInvoice",
                    "HospitalPayment"
                ],
                "parameters": [
                    {
                        "name": "invoiceId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    },
                    {
                        "name": "paymentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Payment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/lab-orders": {
            "get": {
                "operationId": "get_api_hospital_lab_orders",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "List lab orders",
                "description": "Paginated lab orders with patient, doctor, tests, priority, status and result dates. Filter by `status`, `patient_id`, `priority`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@orders",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L115-L168",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "LabOrder"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "doctor_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Doctor."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "patient_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Patient."
                    },
                    {
                        "name": "pending",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = not completed / cancelled."
                    },
                    {
                        "name": "priority",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Priority."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`lab_orders[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "lab_orders": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_lab_orders",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Create a lab order",
                "description": "Generates a `LAB-…` reference and one item per test.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@storeOrder",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L179-L206",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabOrder"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Ordering doctor."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "ordered_at": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Order date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "priority": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "routine",
                                            "urgent",
                                            "stat"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:routine,urgent,stat"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`routine`, `urgent`, `stat`."
                                    },
                                    "test_ids": {
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Lab test ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "visit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "patient_visits,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:patient_visits,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Related visit."
                                    }
                                },
                                "required": [
                                    "patient_id",
                                    "test_ids"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/lab-orders/delete/by_selection": {
            "post": {
                "operationId": "post_api_hospital_lab_orders_delete_by_selection",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Delete selected lab orders",
                "description": "Bulk delete of lab orders by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@deleteBySelection",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L286-L297",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabOrderItem",
                    "LabOrder"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/lab-orders/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_lab_orders_id",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Delete a lab order",
                "description": "Deletes a lab order and its results.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@destroyOrder",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L273-L284",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabOrder",
                    "LabOrderItem"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_hospital_lab_orders_id",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Get a lab order",
                "description": "Order with its `items[]` (test, result, unit, normal range, flag).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@showOrder",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L170-L177",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`lab_order`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "lab_order": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_lab_orders_id",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Update a lab order",
                "description": "Results already entered survive changes to the test list.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@updateOrder",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L208-L232",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Ordering doctor."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "ordered_at": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Order date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "priority": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "routine",
                                            "urgent",
                                            "stat"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:routine,urgent,stat"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`routine`, `urgent`, `stat`."
                                    },
                                    "test_ids": {
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Lab test ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "visit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "patient_visits,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:patient_visits,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Related visit."
                                    }
                                },
                                "required": [
                                    "patient_id",
                                    "test_ids"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/lab-orders/{id}/results": {
            "post": {
                "operationId": "post_api_hospital_lab_orders_id_results",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Enter results",
                "description": "Saves per-item results and the order status; `completed` stamps `completed_at`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@saveResults",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L238-L271",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabOrder",
                    "LabOrderItem"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "results": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "flag": {
                                                    "x-inferred": true,
                                                    "type": "string",
                                                    "enum": [
                                                        "normal",
                                                        "low",
                                                        "high",
                                                        "critical"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "in:normal,low,high,critical"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`normal`, `low`, `high`, `critical`."
                                                },
                                                "id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Order item id."
                                                }
                                            },
                                            "required": [
                                                "id"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Per-item results."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "ordered",
                                            "sample_collected",
                                            "in_progress",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:ordered,sample_collected,in_progress,completed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Order status."
                                    },
                                    "results.*.result": {
                                        "type": "string",
                                        "description": "Result value.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "results.*.notes": {
                                        "type": "string",
                                        "description": "Notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/lab-tests": {
            "get": {
                "operationId": "get_api_hospital_lab_tests",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "List lab tests",
                "description": "Catalogue with `categories[]`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@tests",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L29-L80",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "LabTest"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` / `0`."
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`lab_tests[]`, `categories[]`, `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "lab_tests": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_lab_tests",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Create a lab test",
                "description": "Creates a lab test in the catalogue: code, name, category, sample type, unit, normal range, price and turnaround time.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@storeTest",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L82-L90",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabTest"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Category (e.g. Haematology)."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "normal_range": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference range."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Price."
                                    },
                                    "sample_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sample (blood, urine…)."
                                    },
                                    "turnaround_hours": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 2000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Turnaround time."
                                    },
                                    "unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Result unit."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "category": {},
                                        "sample_type": {},
                                        "unit": {},
                                        "normal_range": {},
                                        "price": {},
                                        "turnaround_hours": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/lab-tests/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_lab_tests_id",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Delete a lab test",
                "description": "Deletes a lab test from the catalogue. Tests already used in orders are kept on those orders.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@destroyTest",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L102-L109",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabTest"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Test id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_lab_tests_id",
                "tags": [
                    "Hospital: Laboratory"
                ],
                "summary": "Update a lab test",
                "description": "Updates a lab test with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalLabController@updateTest",
                "x-source": "app/Http/Controllers/HospitalLabController.php#L92-L100",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "LabOrderPolicy"
                    }
                ],
                "x-models": [
                    "LabTest"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Test id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Category (e.g. Haematology)."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "normal_range": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference range."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Price."
                                    },
                                    "sample_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sample (blood, urine…)."
                                    },
                                    "turnaround_hours": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 2000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Turnaround time."
                                    },
                                    "unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Result unit."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "category": {},
                                        "sample_type": {},
                                        "unit": {},
                                        "normal_range": {},
                                        "price": {},
                                        "turnaround_hours": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/meta": {
            "get": {
                "operationId": "get_api_hospital_meta",
                "tags": [
                    "Hospital: Dashboard"
                ],
                "summary": "Hospital form lookups",
                "description": "Active `departments`, `doctors` (with fee), `wards` and `lab_tests`. Patients are searched separately.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDashboardController@meta",
                "x-source": "app/Http/Controllers/HospitalDashboardController.php#L177-L211",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "hms_patients_view",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "HospitalDepartment",
                    "Doctor",
                    "HospitalWard",
                    "LabTest"
                ],
                "responses": {
                    "200": {
                        "description": "Lookup lists.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "departments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "doctors": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "wards": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "lab_tests": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/patients": {
            "get": {
                "operationId": "get_api_hospital_patients",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "List patients",
                "description": "Sortable `id, mrn, name, gender, date_of_birth, phone, status, created_at`; `search` matches name, MRN, phone or national id.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@index",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L33-L87",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "hms_patients_view",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Patient",
                    "Admission"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "admitted",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = currently admitted."
                    },
                    {
                        "name": "blood_group",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Blood group."
                    },
                    {
                        "name": "gender",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Gender."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`active`, `inactive`, `deceased`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`patients[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "patients": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_patients",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "Register a patient",
                "description": "Multipart. `mrn` is generated when omitted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@store",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L89-L102",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "hms_patients_add",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "allergies": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allergies."
                                    },
                                    "blood_group": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "A+",
                                            "A-",
                                            "B+",
                                            "B-",
                                            "AB+",
                                            "AB-",
                                            "O+",
                                            "O-"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:A+,A-,B+,B-,AB+,AB-,O+,O-"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Blood group."
                                    },
                                    "chronic_conditions": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Chronic conditions."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked customer (for POS billing)."
                                    },
                                    "date_of_birth": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "before_or_equal:today"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "before_or_equal:today"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date of birth."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "emergency_contact_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Emergency contact."
                                    },
                                    "emergency_contact_phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Emergency phone."
                                    },
                                    "emergency_contact_relation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Relation."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "male",
                                            "female",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:male,female,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`male`, `female`, `other`."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "insurance_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Insurance expiry."
                                    },
                                    "insurance_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Policy number."
                                    },
                                    "insurance_provider": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Insurer."
                                    },
                                    "mrn": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'nullable|string|max:32|unique:patients,mrn' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'nullable|string|max:32|unique:patients,mrn' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Medical record number (unique)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Full name."
                                    },
                                    "national_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "National id.",
                                        "type": "string"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "inactive",
                                            "deceased"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,inactive,deceased"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`active`, `inactive`, `deceased`."
                                    }
                                },
                                "required": [
                                    "gender",
                                    "name",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `mrn`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "gender": {},
                                        "date_of_birth": {},
                                        "phone": {},
                                        "email": {},
                                        "address": {},
                                        "city": {},
                                        "national_id": {},
                                        "blood_group": {},
                                        "allergies": {},
                                        "chronic_conditions": {},
                                        "emergency_contact_name": {},
                                        "emergency_contact_phone": {},
                                        "emergency_contact_relation": {},
                                        "insurance_provider": {},
                                        "insurance_number": {},
                                        "insurance_expiry": {},
                                        "client_id": {},
                                        "notes": {},
                                        "status": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "mrn": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/patients/delete/by_selection": {
            "post": {
                "operationId": "post_api_hospital_patients_delete_by_selection",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "Delete selected patients",
                "description": "Bulk soft-delete of patients by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@deleteBySelection",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L209-L217",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "hms_patients_delete",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Patient ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/patients/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_patients_id",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "Delete a patient",
                "description": "Soft-deletes a patient. Visits, admissions and invoices are kept for the record.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@destroy",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L200-L207",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "hms_patients_delete",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Patient id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_hospital_patients_id",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "Get a patient",
                "description": "Clinical summary: demographics, insurance, counts of visits / admissions / lab orders, outstanding balance, current admission.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@show",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L105-L159",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "hms_patients_view",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient",
                    "HospitalInvoice",
                    "Admission",
                    "PatientVisit",
                    "Appointment",
                    "LabOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Patient id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`patient`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/patients/{id}/edit": {
            "get": {
                "operationId": "get_api_hospital_patients_id_edit",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "Edit-form data for a patient",
                "description": "The patient with the lookups (blood groups, linked customer) needed by the edit form.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@edit",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L161-L172",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "hms_patients_edit",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Patient id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`patient` with `image_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/patients/{id}/timeline": {
            "get": {
                "operationId": "get_api_hospital_patients_id_timeline",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "Patient timeline",
                "description": "Everything filed under one patient, for the detail page's tabs.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@timeline",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L220-L302",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "hms_patients_view",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient",
                    "PatientVisit",
                    "Appointment",
                    "Admission",
                    "LabOrder",
                    "Prescription",
                    "HospitalInvoice"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Patient id."
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Rows per list (default 50)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`visits[]`, `appointments[]`, `admissions[]`, `lab_orders[]`, `prescriptions[]`, `invoices[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "visits": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "appointments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "admissions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "lab_orders": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "prescriptions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "invoices": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/patients/{id}/update": {
            "post": {
                "operationId": "post_api_hospital_patients_id_update",
                "tags": [
                    "Hospital: Patients"
                ],
                "summary": "Update a patient",
                "description": "Multipart POST; same fields as create plus `remove_image`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalPatientController@update",
                "x-source": "app/Http/Controllers/HospitalPatientController.php#L174-L198",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "hms_patients_edit",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Patient id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "allergies": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allergies."
                                    },
                                    "blood_group": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "A+",
                                            "A-",
                                            "B+",
                                            "B-",
                                            "AB+",
                                            "AB-",
                                            "O+",
                                            "O-"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:A+,A-,B+,B-,AB+,AB-,O+,O-"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Blood group."
                                    },
                                    "chronic_conditions": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Chronic conditions."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked customer (for POS billing)."
                                    },
                                    "date_of_birth": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "before_or_equal:today"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "before_or_equal:today"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date of birth."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "emergency_contact_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Emergency contact."
                                    },
                                    "emergency_contact_phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Emergency phone."
                                    },
                                    "emergency_contact_relation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Relation."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "male",
                                            "female",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:male,female,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`male`, `female`, `other`."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "insurance_expiry": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Insurance expiry."
                                    },
                                    "insurance_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Policy number."
                                    },
                                    "insurance_provider": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Insurer."
                                    },
                                    "mrn": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'nullable|string|max:32|unique:patients,mrn' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'nullable|string|max:32|unique:patients,mrn' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Medical record number (unique)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Full name."
                                    },
                                    "national_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "National id.",
                                        "type": "string"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "remove_image": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remove photo.",
                                        "type": "boolean"
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "inactive",
                                            "deceased"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,inactive,deceased"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`active`, `inactive`, `deceased`."
                                    }
                                },
                                "required": [
                                    "gender",
                                    "name",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "gender": {},
                                        "date_of_birth": {},
                                        "phone": {},
                                        "email": {},
                                        "address": {},
                                        "city": {},
                                        "national_id": {},
                                        "blood_group": {},
                                        "allergies": {},
                                        "chronic_conditions": {},
                                        "emergency_contact_name": {},
                                        "emergency_contact_phone": {},
                                        "emergency_contact_relation": {},
                                        "insurance_provider": {},
                                        "insurance_number": {},
                                        "insurance_expiry": {},
                                        "client_id": {},
                                        "notes": {},
                                        "status": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/payments": {
            "get": {
                "operationId": "get_api_hospital_payments",
                "tags": [
                    "Hospital: Billing"
                ],
                "summary": "List payments",
                "description": "Paginated payments received on hospital invoices with invoice, patient, amount, method and date. Filter by date range and method.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalBillingController@payments",
                "x-source": "app/Http/Controllers/HospitalBillingController.php#L254-L309",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "HospitalInvoicePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "HospitalPayment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "method",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Method."
                    },
                    {
                        "name": "patient_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Patient."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]`, `totalRows`, `collected`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "collected": {},
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/reports/collections": {
            "get": {
                "operationId": "get_api_hospital_reports_collections",
                "tags": [
                    "Hospital: Reports"
                ],
                "summary": "Collections by payment method",
                "description": "Collections by payment method.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalReportController@collections",
                "x-source": "app/Http/Controllers/HospitalReportController.php#L245-L272",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "hms_reports",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "HospitalPayment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[] {method, payments, amount}`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/reports/doctors": {
            "get": {
                "operationId": "get_api_hospital_reports_doctors",
                "tags": [
                    "Hospital: Reports"
                ],
                "summary": "Doctor workload report",
                "description": "Doctor workload: appointments, visits, patients seen, revenue.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalReportController@doctors",
                "x-source": "app/Http/Controllers/HospitalReportController.php#L31-L73",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "hms_reports",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Doctor",
                    "PatientVisit"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (appointments, no-shows, visits, patients, fees), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/reports/occupancy": {
            "get": {
                "operationId": "get_api_hospital_reports_occupancy",
                "tags": [
                    "Hospital: Reports"
                ],
                "summary": "Ward occupancy report",
                "description": "Ward occupancy and inpatient throughput.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalReportController@occupancy",
                "x-source": "app/Http/Controllers/HospitalReportController.php#L130-L180",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "hms_reports",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "HospitalWard",
                    "Admission"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (beds by status, admissions, discharges, average stay), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/reports/patients": {
            "get": {
                "operationId": "get_api_hospital_reports_patients",
                "tags": [
                    "Hospital: Reports"
                ],
                "summary": "Patient activity report",
                "description": "Patient activity: who is using the hospital, and what they owe.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalReportController@patients",
                "x-source": "app/Http/Controllers/HospitalReportController.php#L183-L242",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "hms_reports",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PatientVisit",
                    "HospitalInvoice",
                    "Patient"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (visits, last visit, billed, paid, due), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/reports/revenue": {
            "get": {
                "operationId": "get_api_hospital_reports_revenue",
                "tags": [
                    "Hospital: Reports"
                ],
                "summary": "Revenue by department",
                "description": "Revenue by department: what was billed and what was actually collected.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalReportController@revenue",
                "x-source": "app/Http/Controllers/HospitalReportController.php#L76-L127",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "hms_reports",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PatientVisit",
                    "HospitalDepartment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (visits, invoices, billed, collected), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/search/medicines": {
            "get": {
                "operationId": "get_api_hospital_search_medicines",
                "tags": [
                    "Hospital: Dashboard"
                ],
                "summary": "Medicine type-ahead",
                "description": "Searches the product catalogue for prescription lines.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDashboardController@searchMedicines",
                "x-source": "app/Http/Controllers/HospitalDashboardController.php#L272-L295",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "hms_patients_view",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name or code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`medicines[]` (max 20).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "medicines": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/search/patients": {
            "get": {
                "operationId": "get_api_hospital_search_patients",
                "tags": [
                    "Hospital: Dashboard"
                ],
                "summary": "Patient type-ahead",
                "description": "Type-ahead over patients for every form that needs one. Capped at 20 — a picker is for finding a known patient, not browsing the register. /",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalDashboardController@searchPatients",
                "x-source": "app/Http/Controllers/HospitalDashboardController.php#L239-L266",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "hms_patients_view",
                        "policy": "PatientPolicy"
                    }
                ],
                "x-models": [
                    "Patient"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name, MRN or phone."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`patients[]` (max 20).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patients": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/visits": {
            "get": {
                "operationId": "get_api_hospital_visits",
                "tags": [
                    "Hospital: Visits & Prescriptions"
                ],
                "summary": "List visits",
                "description": "Paginated OPD visits with patient, doctor, department, date, diagnosis and status. Filter by `doctor_id`, `patient_id`, `status`, date range.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalVisitController@index",
                "x-source": "app/Http/Controllers/HospitalVisitController.php#L27-L82",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "PatientVisitPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PatientVisit"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    },
                    {
                        "name": "doctor_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Doctor."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "patient_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Patient."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`open` / `completed`."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Type."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`visits[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "visits": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_visits",
                "tags": [
                    "Hospital: Visits & Prescriptions"
                ],
                "summary": "Record a visit",
                "description": "Generates a `VIS-…` reference; `fee` defaults to the doctor's fee. `prescription_items` creates the prescription; a `completed` visit closes its appointment.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalVisitController@store",
                "x-source": "app/Http/Controllers/HospitalVisitController.php#L105-L137",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "PatientVisitPolicy"
                    }
                ],
                "x-models": [
                    "PatientVisit",
                    "Doctor",
                    "Appointment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "appointment_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "appointments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:appointments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source appointment."
                                    },
                                    "bp_diastolic": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Diastolic BP."
                                    },
                                    "bp_systolic": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,300"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Systolic BP."
                                    },
                                    "complaint": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Chief complaint."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "diagnosis": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Diagnosis."
                                    },
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Doctor."
                                    },
                                    "examination": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Findings."
                                    },
                                    "fee": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Consultation fee."
                                    },
                                    "follow_up_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Follow-up date."
                                    },
                                    "height": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "between:0,300"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "cm."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "prescription_items": {
                                        "description": "Lines: `[{product_id?, medicine, dosage, frequency, duration, quantity, instructions}]`.",
                                        "x-sources": [
                                            "documented"
                                        ],
                                        "type": "array",
                                        "items": {}
                                    },
                                    "prescription_notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Prescription notes."
                                    },
                                    "pulse": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,300"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "bpm."
                                    },
                                    "respiratory_rate": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Breaths/min."
                                    },
                                    "spo2": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Oxygen saturation %."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "open",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:open,completed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`open` or `completed`."
                                    },
                                    "temperature": {
                                        "type": "number",
                                        "minimum": 20,
                                        "maximum": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "between:20,50"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "°C."
                                    },
                                    "treatment_plan": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Plan."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "opd",
                                            "emergency",
                                            "follow_up",
                                            "teleconsult"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:opd,emergency,follow_up,teleconsult"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Visit type."
                                    },
                                    "visit_date": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "weight": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 600,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "between:0,600"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "kg."
                                    }
                                },
                                "required": [
                                    "patient_id",
                                    "status",
                                    "type",
                                    "visit_date"
                                ]
                            },
                            "example": {
                                "patient_id": 12,
                                "doctor_id": 3,
                                "visit_date": "2026-09-06 10:30:00",
                                "type": "opd",
                                "status": "completed",
                                "temperature": 37.2,
                                "pulse": 78,
                                "bp_systolic": 120,
                                "bp_diastolic": 80,
                                "complaint": "Headache",
                                "diagnosis": "Tension headache",
                                "prescription_items": [
                                    {
                                        "product_id": 88,
                                        "medicine": "Paracetamol 500mg",
                                        "dosage": "1 tab",
                                        "frequency": "3x/day",
                                        "duration": "5 days",
                                        "quantity": 15
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient_id": {},
                                        "doctor_id": {},
                                        "department_id": {},
                                        "appointment_id": {},
                                        "visit_date": {},
                                        "type": {},
                                        "temperature": {},
                                        "pulse": {},
                                        "bp_systolic": {},
                                        "bp_diastolic": {},
                                        "respiratory_rate": {},
                                        "spo2": {},
                                        "weight": {},
                                        "height": {},
                                        "complaint": {},
                                        "examination": {},
                                        "diagnosis": {},
                                        "treatment_plan": {},
                                        "follow_up_date": {},
                                        "status": {},
                                        "fee": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/visits/delete/by_selection": {
            "post": {
                "operationId": "post_api_hospital_visits_delete_by_selection",
                "tags": [
                    "Hospital: Visits & Prescriptions"
                ],
                "summary": "Delete selected visits",
                "description": "Bulk delete of visits by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalVisitController@deleteBySelection",
                "x-source": "app/Http/Controllers/HospitalVisitController.php#L171-L179",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "PatientVisitPolicy"
                    }
                ],
                "x-models": [
                    "PatientVisit"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Visit ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/visits/from-appointment/{appointmentId}": {
            "get": {
                "operationId": "get_api_hospital_visits_from_appointment_appointmentId",
                "tags": [
                    "Hospital: Visits & Prescriptions"
                ],
                "summary": "Prefill a visit from an appointment",
                "description": "Prefill a consultation from a booked appointment.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalVisitController@fromAppointment",
                "x-source": "app/Http/Controllers/HospitalVisitController.php#L182-L199",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "PatientVisitPolicy"
                    }
                ],
                "x-models": [
                    "Appointment"
                ],
                "parameters": [
                    {
                        "name": "appointmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Appointment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`prefill` (patient, doctor, department, date, complaint, fee, type).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "prefill": {
                                            "type": "object",
                                            "properties": {
                                                "appointment_id": {},
                                                "patient_id": {},
                                                "patient_name": {},
                                                "doctor_id": {},
                                                "department_id": {},
                                                "visit_date": {
                                                    "type": "string"
                                                },
                                                "complaint": {},
                                                "fee": {
                                                    "type": "number"
                                                },
                                                "type": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/visits/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_visits_id",
                "tags": [
                    "Hospital: Visits & Prescriptions"
                ],
                "summary": "Delete a visit",
                "description": "Deletes a visit with its vitals and prescription. Invoiced visits cannot be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalVisitController@destroy",
                "x-source": "app/Http/Controllers/HospitalVisitController.php#L162-L169",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "PatientVisitPolicy"
                    }
                ],
                "x-models": [
                    "PatientVisit"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Visit id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_hospital_visits_id",
                "tags": [
                    "Hospital: Visits & Prescriptions"
                ],
                "summary": "Get a visit",
                "description": "Visit with `vitals` and its `prescription` (lines).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalVisitController@show",
                "x-source": "app/Http/Controllers/HospitalVisitController.php#L84-L103",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "PatientVisitPolicy"
                    }
                ],
                "x-models": [
                    "PatientVisit"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Visit id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`visit`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "visit": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_visits_id",
                "tags": [
                    "Hospital: Visits & Prescriptions"
                ],
                "summary": "Update a visit",
                "description": "Same fields as create; the prescription is re-synced.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalVisitController@update",
                "x-source": "app/Http/Controllers/HospitalVisitController.php#L139-L160",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "PatientVisitPolicy"
                    }
                ],
                "x-models": [
                    "PatientVisit",
                    "Appointment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Visit id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "appointment_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "appointments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:appointments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source appointment."
                                    },
                                    "bp_diastolic": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Diastolic BP."
                                    },
                                    "bp_systolic": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,300"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Systolic BP."
                                    },
                                    "complaint": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Chief complaint."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "diagnosis": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Diagnosis."
                                    },
                                    "doctor_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "doctors,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:doctors,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Doctor."
                                    },
                                    "examination": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Findings."
                                    },
                                    "fee": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Consultation fee."
                                    },
                                    "follow_up_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Follow-up date."
                                    },
                                    "height": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "between:0,300"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "cm."
                                    },
                                    "patient_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "patients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:patients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Patient."
                                    },
                                    "prescription_items": {
                                        "description": "Lines: `[{product_id?, medicine, dosage, frequency, duration, quantity, instructions}]`.",
                                        "x-sources": [
                                            "documented"
                                        ],
                                        "type": "array",
                                        "items": {}
                                    },
                                    "prescription_notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Prescription notes."
                                    },
                                    "pulse": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 300,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,300"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "bpm."
                                    },
                                    "respiratory_rate": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Breaths/min."
                                    },
                                    "spo2": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "between:0,100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Oxygen saturation %."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "open",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:open,completed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`open` or `completed`."
                                    },
                                    "temperature": {
                                        "type": "number",
                                        "minimum": 20,
                                        "maximum": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "between:20,50"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "°C."
                                    },
                                    "treatment_plan": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Plan."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "opd",
                                            "emergency",
                                            "follow_up",
                                            "teleconsult"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:opd,emergency,follow_up,teleconsult"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Visit type."
                                    },
                                    "visit_date": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "weight": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 600,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "between:0,600"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "kg."
                                    }
                                },
                                "required": [
                                    "patient_id",
                                    "status",
                                    "type",
                                    "visit_date"
                                ]
                            },
                            "example": {
                                "patient_id": 12,
                                "doctor_id": 3,
                                "visit_date": "2026-09-06 10:30:00",
                                "type": "opd",
                                "status": "completed",
                                "temperature": 37.2,
                                "pulse": 78,
                                "bp_systolic": 120,
                                "bp_diastolic": 80,
                                "complaint": "Headache",
                                "diagnosis": "Tension headache",
                                "prescription_items": [
                                    {
                                        "product_id": 88,
                                        "medicine": "Paracetamol 500mg",
                                        "dosage": "1 tab",
                                        "frequency": "3x/day",
                                        "duration": "5 days",
                                        "quantity": 15
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "patient_id": {},
                                        "doctor_id": {},
                                        "department_id": {},
                                        "appointment_id": {},
                                        "visit_date": {},
                                        "type": {},
                                        "temperature": {},
                                        "pulse": {},
                                        "bp_systolic": {},
                                        "bp_diastolic": {},
                                        "respiratory_rate": {},
                                        "spo2": {},
                                        "weight": {},
                                        "height": {},
                                        "complaint": {},
                                        "examination": {},
                                        "diagnosis": {},
                                        "treatment_plan": {},
                                        "follow_up_date": {},
                                        "status": {},
                                        "fee": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/wards": {
            "get": {
                "operationId": "get_api_hospital_wards",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "List wards",
                "description": "Wards with department, floor, type, daily rate, bed count and occupancy.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@index",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L27-L74",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "HospitalWard"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Department."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Ward type."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`wards[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "wards": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_hospital_wards",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "Create a ward",
                "description": "Creates a ward (name, department, floor, type, daily rate).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@store",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L76-L84",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-models": [
                    "HospitalWard"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "daily_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default bed rate."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "floor": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Floor."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "general",
                                            "private",
                                            "semi_private",
                                            "icu",
                                            "nicu",
                                            "maternity",
                                            "isolation"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:general,private,semi_private,icu,nicu,maternity,isolation"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Ward type."
                                    }
                                },
                                "required": [
                                    "name",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "department_id": {},
                                        "type": {},
                                        "floor": {},
                                        "daily_rate": {},
                                        "is_active": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/hospital/wards/{id}": {
            "delete": {
                "operationId": "delete_api_hospital_wards_id",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "Delete a ward",
                "description": "Refused while any bed is occupied; deletes its beds.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@destroy",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L96-L113",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-models": [
                    "HospitalWard",
                    "HospitalBed"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Ward id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Occupied beds.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This ward still has {$occupied} occupied bed(s). Discharge or transfer those patients first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_hospital_wards_id",
                "tags": [
                    "Hospital: Wards & Beds"
                ],
                "summary": "Update a ward",
                "description": "Updates a ward with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "HospitalWardController@update",
                "x-source": "app/Http/Controllers/HospitalWardController.php#L86-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "HospitalWardPolicy"
                    }
                ],
                "x-models": [
                    "HospitalWard"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Ward id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "daily_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default bed rate."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "hospital_departments,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:hospital_departments,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "floor": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Floor."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "general",
                                            "private",
                                            "semi_private",
                                            "icu",
                                            "nicu",
                                            "maternity",
                                            "isolation"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:general,private,semi_private,icu,nicu,maternity,isolation"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Ward type."
                                    }
                                },
                                "required": [
                                    "name",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "department_id": {},
                                        "type": {},
                                        "floor": {},
                                        "daily_rate": {},
                                        "is_active": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/jumia/logs": {
            "delete": {
                "operationId": "delete_api_jumia_logs",
                "tags": [
                    "Jumia"
                ],
                "summary": "Clear Jumia logs",
                "description": "Clears the Jumia sync log.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@clearLogs",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L135-L142",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "x-models": [
                    "JumiaLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_jumia_logs",
                "tags": [
                    "Jumia"
                ],
                "summary": "Jumia logs",
                "description": "Paginated Jumia sync log (type, status, message, counts, timestamp).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@logs",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L123-L133",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "JumiaLog"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Level."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/jumia/settings": {
            "get": {
                "operationId": "get_api_jumia_settings",
                "tags": [
                    "Jumia"
                ],
                "summary": "Get Jumia settings",
                "description": "Current Jumia Seller Center settings; the API key is masked.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@settings",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L19-L35",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "x-models": [
                    "JumiaSetting",
                    "Warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `configured`, `api_url`, `user_email`, `has_api_key`, `warehouse_id`, `warehouses[]`, `last_sync_at`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "configured": {},
                                        "api_url": {},
                                        "user_email": {},
                                        "has_api_key": {},
                                        "warehouse_id": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "last_sync_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_jumia_settings",
                "tags": [
                    "Jumia"
                ],
                "summary": "Save Jumia settings",
                "description": "Saves the Jumia API endpoint, user email, API key, default warehouse/customer and the sync options.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@saveSettings",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L37-L67",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "x-models": [
                    "JumiaSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "api_key": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "API key (write-only)."
                                    },
                                    "api_url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191",
                                            "url"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Seller Center API URL."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "user_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Seller account email."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse whose stock is published."
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `configured`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "configured": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/jumia/stats": {
            "get": {
                "operationId": "get_api_jumia_stats",
                "tags": [
                    "Jumia"
                ],
                "summary": "Sync statistics",
                "description": "Counters for the dashboard card: synced products, orders imported, last sync times.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@stats",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L86-L91",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Counts.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/jumia/sync/orders": {
            "post": {
                "operationId": "post_api_jumia_sync_orders",
                "tags": [
                    "Jumia"
                ],
                "summary": "Pull orders into sales",
                "description": "Fetches new Jumia orders and creates the corresponding sales (customer, lines, status). Already imported orders are skipped.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@syncOrders",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L107-L121",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "page_info": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Page number (default 1).",
                                        "type": "integer"
                                    },
                                    "per_page": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Orders per page (default 20).",
                                        "type": "integer"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse for the created sales."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `imported`, `skipped`, `next_page`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/jumia/sync/price-stock": {
            "post": {
                "operationId": "post_api_jumia_sync_price_stock",
                "tags": [
                    "Jumia"
                ],
                "summary": "Push price and stock",
                "description": "Pushes current price and stock of mapped products to Jumia.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@syncPriceStock",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L93-L105",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call (default 100).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `pushed`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/jumia/test-connection": {
            "post": {
                "operationId": "post_api_jumia_test_connection",
                "tags": [
                    "Jumia"
                ],
                "summary": "Test the Jumia connection",
                "description": "Calls the Jumia API with the stored credentials and reports success or the error returned.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\JumiaSyncController@testConnection",
                "x-source": "app/Http/Controllers/Integrations/JumiaSyncController.php#L69-L84",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "JumiaSettingPolicy"
                    }
                ],
                "x-models": [
                    "JumiaSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not configured / failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Add the API URL, email and key first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/orders": {
            "get": {
                "operationId": "get_api_kitchen_orders",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "List kitchen tickets (board)",
                "description": "All tickets matching the filters, oldest first, each mapped with customer, assigned user, dispatched warehouse, sale lines and per-line `item_states`. Returns the flat `data[]`, the same tickets `grouped` by status (`pending`, `preparing`, `completed`, `on_hold`), per-status `counts`, the `warehouses` lookup for dispatching, the `target_minutes` prep target used for overdue colouring, and the configured `stations`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@index",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L21-L73",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "kitchen_display_view",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder",
                    "Setting",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Created on/after this date."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search on ticket ref, customer name or phone."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `preparing`, `completed` or `on_hold`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Created on/before this date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]`, `grouped`, `counts`, `warehouses[]`, `target_minutes`, `stations[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "grouped": {},
                                        "counts": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "target_minutes": {
                                            "type": "integer"
                                        },
                                        "stations": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_kitchen_orders",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Send a sale to the kitchen",
                "description": "Creates a ticket for an existing sale (*Send later* from the sales list). If the sale already has a ticket it is returned with `already_sent: true` instead of creating a duplicate. New tickets return HTTP **201**.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@store",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L113-L141",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "manage",
                        "slug": "kitchen_display_manage",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "instructions": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Kitchen instructions / notes."
                                    },
                                    "sale_id": {
                                        "type": "integer",
                                        "x-exists": "sales,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:sales,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sale to send."
                                    }
                                },
                                "required": [
                                    "sale_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`already_sent: true` with the existing `order`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "already_sent": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "order": {}
                                    }
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`ok` and the new `order`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "order": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Sale not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Sale not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/orders/poll": {
            "get": {
                "operationId": "get_api_kitchen_orders_poll",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Poll for kitchen changes",
                "description": "Cheap heartbeat for the board: `latest_id`, `last_update` timestamp and per-status `counts`; the client reloads the list only when these change.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@poll",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L79-L95",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "kitchen_display_view",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder"
                ],
                "responses": {
                    "200": {
                        "description": "`latest_id`, `last_update`, `counts`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "$s": {
                                            "type": "integer"
                                        },
                                        "latest_id": {
                                            "type": "integer"
                                        },
                                        "last_update": {
                                            "type": "string"
                                        },
                                        "counts": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/orders/{id}": {
            "get": {
                "operationId": "get_api_kitchen_orders_id",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Get a kitchen ticket",
                "description": "One ticket with customer, warehouse, assigned user, sender and dispatched warehouse, the sale lines and `item_states`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@show",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L100-L107",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "kitchen_display_view",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Kitchen order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Ticket object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/orders/{id}/assign": {
            "patch": {
                "operationId": "patch_api_kitchen_orders_id_assign",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Assign a ticket to a cook",
                "description": "Sets or clears (`null`) the user responsible for the ticket.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@assign",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L231-L247",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "manage",
                        "slug": "kitchen_display_manage",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Kitchen order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "users,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:users,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "User id, or `null` to unassign."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok` and `order`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "order": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/orders/{id}/dispatch": {
            "patch": {
                "operationId": "patch_api_kitchen_orders_id_dispatch",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Record hand-off to a warehouse",
                "description": "Marks which warehouse / counter a **completed** ticket was handed to (`dispatched_warehouse_id`, `dispatched_at`). Informational only — no stock transfer is created.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@dispatchOrder",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L330-L352",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "manage",
                        "slug": "kitchen_display_manage",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Kitchen order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "dispatched_warehouse_id": {
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                },
                                "required": [
                                    "dispatched_warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok` and `order`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "order": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/orders/{id}/item": {
            "patch": {
                "operationId": "patch_api_kitchen_orders_id_item",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Bump one line of a ticket",
                "description": "Toggles the `done` flag of a single sale line. Checking the first item of a `pending`/`on_hold` ticket moves it to `preparing`; checking the last remaining item completes the ticket (`auto_completed: true`). Unchecking never demotes a completed ticket.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@updateItem",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L177-L226",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "manage",
                        "slug": "kitchen_display_manage",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder",
                    "SaleDetail"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Kitchen order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "done": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`true` to mark done, `false` to uncheck."
                                    },
                                    "item_id": {
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sale detail id of the line."
                                    }
                                },
                                "required": [
                                    "done",
                                    "item_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `auto_completed`, `order`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "auto_completed": {},
                                        "order": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/orders/{id}/status": {
            "patch": {
                "operationId": "patch_api_kitchen_orders_id_status",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Change a ticket's status",
                "description": "Sets the ticket status. Moving to `preparing` stamps `started_at` (first time only); `completed` stamps `completed_at`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@updateStatus",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L146-L170",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "manage",
                        "slug": "kitchen_display_manage",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "KitchenOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Kitchen order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "preparing",
                                            "completed",
                                            "on_hold"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:pending,preparing,completed,on_hold"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`pending`, `preparing`, `completed` or `on_hold`."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok` and the updated `order`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "order": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/ready-screen/data": {
            "get": {
                "operationId": "get_api_kitchen_ready_screen_data",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Get Order-Ready screen data",
                "description": "**Public, token-guarded.** Labels (token number or ref) of today's tickets still in the kitchen (`preparing`) and of tickets completed in the last 4 hours (`ready`), max 60 each.",
                "x-section": "Point of Sale",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "KitchenOrderController@readyScreenData",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L378-L404",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "KitchenOrder"
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Token from *Generate an Order-Ready screen token*."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`preparing[]`, `ready[]`, `ts`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "preparing": {},
                                        "ready": {},
                                        "ts": {}
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Invalid token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Unauthorized"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/kitchen/ready-screen/generate": {
            "post": {
                "operationId": "post_api_kitchen_ready_screen_generate",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Generate an Order-Ready screen token",
                "description": "Creates a token valid 7 days for the public `/order-ready?token=…` page shown on a wall TV.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@generateReadyScreen",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L360-L371",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "kitchen_display_view",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`token` and `url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "token": {
                                            "type": "string"
                                        },
                                        "url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/report": {
            "get": {
                "operationId": "get_api_kitchen_report",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Kitchen performance report",
                "description": "Paginated per-ticket rows (`ref, token_number, source, status, customer_name, staff_name, sent_at, started_at, completed_at, wait_minutes, prep_minutes, total_minutes`) for the period (default last 30 days), plus `kpis` (tickets, averages, overdue count vs `target_minutes`), a per-day `timeseries` of prep time, `by_staff` summary and `top_products`. Sortable by `ref, token_number, source, status, staff_name, sent_at, wait_minutes, prep_minutes, total_minutes`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@report",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L412-L527",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "kitchen_display_view",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Setting"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (default 29 days ago)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (default today)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`report[]`, `totalRows`, `kpis`, `timeseries[]`, `by_staff[]`, `top_products[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "kpis": {
                                            "type": "object",
                                            "properties": {
                                                "tickets": {
                                                    "type": "integer"
                                                },
                                                "completed": {
                                                    "type": "integer"
                                                },
                                                "avg_wait": {
                                                    "type": "number"
                                                },
                                                "avg_prep": {
                                                    "type": "number"
                                                },
                                                "avg_total": {
                                                    "type": "number"
                                                },
                                                "overdue": {
                                                    "type": "integer"
                                                },
                                                "target_minutes": {}
                                            }
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_staff": {},
                                        "top_products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/stations": {
            "get": {
                "operationId": "get_api_kitchen_stations",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Get prep stations",
                "description": "The configured `stations[]` (`id, name, category_ids[]`) and the `categories` list for the editor.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@stations",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L270-L281",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "kitchen_display_view",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Category"
                ],
                "responses": {
                    "200": {
                        "description": "`stations[]` and `categories[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stations": {},
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_kitchen_stations",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "Replace prep stations",
                "description": "Replaces the whole station list (max 30). Stations without an `id` receive a generated one. Stored in system settings.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@saveStations",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L287-L314",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "manage",
                        "slug": "kitchen_display_manage",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "stations": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "category_ids": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "integer",
                                                        "x-laravel-rules": [
                                                            "integer"
                                                        ]
                                                    },
                                                    "x-conditional": [
                                                        "present"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "present",
                                                        "array"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product category ids routed to this station."
                                                },
                                                "id": {
                                                    "type": "string",
                                                    "maxLength": 40,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:40"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Existing station id (omit for new)."
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "maxLength": 60,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "string",
                                                        "max:60"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Station name, max 60."
                                                }
                                            },
                                            "required": [
                                                "name"
                                            ]
                                        },
                                        "maxItems": 30,
                                        "x-conditional": [
                                            "present"
                                        ],
                                        "x-laravel-rules": [
                                            "present",
                                            "array",
                                            "max:30"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Array of stations."
                                    }
                                }
                            },
                            "example": {
                                "stations": [
                                    {
                                        "id": "st_grill",
                                        "name": "Grill",
                                        "category_ids": [
                                            3,
                                            4
                                        ]
                                    },
                                    {
                                        "name": "Bar",
                                        "category_ids": [
                                            7
                                        ]
                                    }
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok` and normalised `stations[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "stations": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Settings not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/kitchen/warehouses": {
            "get": {
                "operationId": "get_api_kitchen_warehouses",
                "tags": [
                    "Kitchen Orders"
                ],
                "summary": "List warehouses for dispatch",
                "description": "`{id, name}` list of warehouses, gated by the kitchen view permission so kitchen staff need no warehouse permission.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "KitchenOrderController@warehouses",
                "x-source": "app/Http/Controllers/KitchenOrderController.php#L254-L263",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "kitchen_display_view",
                        "policy": "KitchenOrderPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/knowledge-base/articles": {
            "get": {
                "operationId": "get_api_knowledge_base_articles",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "List articles",
                "description": "Laravel-paginated articles with their group, ordered by `sort_order` then title. Internal articles are hidden from users without the manage permission.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleController@index",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleController.php#L19-L45",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "KnowledgeBaseArticle"
                ],
                "parameters": [
                    {
                        "name": "group_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Group filter."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 15, max 50)."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search on title or content."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator with `data[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_knowledge_base_articles",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Create an article",
                "description": "Slug must be unique within the group. Returns HTTP **201**.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleController@store",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleController.php#L47-L70",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "knowledge_base_view",
                        "policy": "KnowledgeBaseArticlePolicy"
                    }
                ],
                "x-models": [
                    "KnowledgeBaseArticle"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "content": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Body (Markdown/HTML)."
                                    },
                                    "is_internal": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Hide from non-managers."
                                    },
                                    "knowledge_base_article_group_id": {
                                        "type": "integer",
                                        "x-exists": "knowledge_base_article_groups,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:knowledge_base_article_groups,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Group."
                                    },
                                    "published_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Publish date."
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-rules": [
                                            "alpha_dash",
                                            "dynamic:$slugRule"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190",
                                            "alpha_dash",
                                            "dynamic:$slugRule"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Slug (alpha-dash)."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sort order (default 0)."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title (max 190)."
                                    }
                                },
                                "required": [
                                    "knowledge_base_article_group_id",
                                    "slug",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The article.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/knowledge-base/articles/{knowledge_base_article}": {
            "delete": {
                "operationId": "delete_api_knowledge_base_articles_knowledge_base_article",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Delete an article",
                "description": "Soft-deletes an article.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleController@destroy",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleController.php#L114-L120",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "knowledge_base_view",
                        "policy": "KnowledgeBaseArticlePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "knowledge_base_article",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Article id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_knowledge_base_articles_knowledge_base_article",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Get an article",
                "description": "The article with its group and `feedback_helpful_count` / `feedback_not_helpful_count`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleController@show",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleController.php#L72-L83",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "view"
                    }
                ],
                "parameters": [
                    {
                        "name": "knowledge_base_article",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Article id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Article object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_knowledge_base_articles_knowledge_base_article",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Update an article",
                "description": "Partial update; only the fields sent are changed.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleController@update",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleController.php#L85-L112",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "knowledge_base_view",
                        "policy": "KnowledgeBaseArticlePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "knowledge_base_article",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Article id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "content": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Body."
                                    },
                                    "is_internal": {
                                        "type": "boolean",
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Internal flag."
                                    },
                                    "knowledge_base_article_group_id": {
                                        "type": "integer",
                                        "x-exists": "knowledge_base_article_groups,id",
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "integer",
                                            "exists:knowledge_base_article_groups,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Group."
                                    },
                                    "published_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Publish date."
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "knowledge_base_articles,slug ->where->ignore",
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-rules": [
                                            "alpha_dash"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "string",
                                            "max:190",
                                            "alpha_dash",
                                            "unique:knowledge_base_articles,slug ->where->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Slug."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "The article.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/knowledge-base/articles/{knowledge_base_article}/feedback": {
            "post": {
                "operationId": "post_api_knowledge_base_articles_knowledge_base_article_feedback",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Rate an article",
                "description": "Records (or updates) the caller's helpful / not-helpful vote.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleController@submitFeedback",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleController.php#L122-L145",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "view"
                    }
                ],
                "x-models": [
                    "KnowledgeBaseArticleFeedback"
                ],
                "parameters": [
                    {
                        "name": "knowledge_base_article",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Article id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "helpful": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`true` = helpful."
                                    }
                                },
                                "required": [
                                    "helpful"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok` and `updated` when an existing vote was changed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "updated": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/knowledge-base/groups": {
            "get": {
                "operationId": "get_api_knowledge_base_groups",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "List article groups",
                "description": "All groups with `articles_count`, ordered by `sort_order` then name.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleGroupController@index",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleGroupController.php#L25-L40",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "knowledge_base_view",
                        "policy": "KnowledgeBaseArticleGroupPolicy"
                    }
                ],
                "x-models": [
                    "KnowledgeBaseArticleGroup"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search on name or slug."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of groups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_knowledge_base_groups",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Create an article group",
                "description": "`sort_order` defaults to the current max + 10. Returns HTTP **201**.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleGroupController@store",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleGroupController.php#L42-L56",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "KnowledgeBaseArticleGroupPolicy"
                    }
                ],
                "x-models": [
                    "KnowledgeBaseArticleGroup"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name (max 190)."
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "knowledge_base_article_groups,slug",
                                        "x-rules": [
                                            "alpha_dash"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190",
                                            "alpha_dash",
                                            "unique:knowledge_base_article_groups,slug"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unique slug (letters, digits, dashes, underscores)."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sort order."
                                    }
                                },
                                "required": [
                                    "name",
                                    "slug"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The group.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/knowledge-base/groups/for-filter": {
            "get": {
                "operationId": "get_api_knowledge_base_groups_for_filter",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Groups for the reader filter",
                "description": "Only groups having at least one non-internal article. Any authenticated user.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleGroupController@forFilter",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleGroupController.php#L14-L23",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "KnowledgeBaseArticleGroup"
                ],
                "responses": {
                    "200": {
                        "description": "`[{id, name, slug}]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/knowledge-base/groups/{knowledge_base_article_group}": {
            "delete": {
                "operationId": "delete_api_knowledge_base_groups_knowledge_base_article_group",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Delete an article group",
                "description": "Deletes an article group. Articles in the group become ungrouped.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleGroupController@destroy",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleGroupController.php#L82-L88",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "KnowledgeBaseArticleGroupPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "knowledge_base_article_group",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Group id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_knowledge_base_groups_knowledge_base_article_group",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Get an article group",
                "description": "One group with its articles.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleGroupController@show",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleGroupController.php#L58-L64",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "KnowledgeBaseArticleGroupPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "knowledge_base_article_group",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Group id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Group with `articles_count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_knowledge_base_groups_knowledge_base_article_group",
                "tags": [
                    "Knowledge Base"
                ],
                "summary": "Update an article group",
                "description": "Renames a group or changes its description / order.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "KnowledgeBaseArticleGroupController@update",
                "x-source": "app/Http/Controllers/KnowledgeBaseArticleGroupController.php#L66-L80",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "KnowledgeBaseArticleGroupPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "knowledge_base_article_group",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Group id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "knowledge_base_article_groups,slug ->ignore",
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-rules": [
                                            "alpha_dash"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "string",
                                            "max:190",
                                            "alpha_dash",
                                            "unique:knowledge_base_article_groups,slug ->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Slug."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sort order."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "The group.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/label_printer_calibrate": {
            "post": {
                "operationId": "post_api_label_printer_calibrate",
                "tags": [
                    "System Settings"
                ],
                "summary": "Calibrate label gap sensor",
                "description": "Sends the configured label size plus TSPL `GAPDETECT` so the printer feeds a few labels and stores the measured sticker/gap lengths. Run after loading a new roll or when positions drift. Accepts `label_printer_*` overrides.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@calibrateLabelPrinter",
                "x-source": "app/Http/Controllers/SettingsController.php#L1485-L1526",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pos_settings",
                        "slug": "pos_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PosSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`{success, qz, printer, payload_base64, message}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "qz": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "printer": {
                                            "type": "string"
                                        },
                                        "payload_base64": {},
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "POS settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "POS settings not found."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/label_printer_dpi_test": {
            "post": {
                "operationId": "post_api_label_printer_dpi_test",
                "tags": [
                    "System Settings"
                ],
                "summary": "Print a DPI detection label",
                "description": "Prints two frames, one computed for 203 dpi and one for 300 dpi, each labelled. The frame whose edges match the sticker reveals the printhead's real resolution. Accepts the same `label_printer_*` overrides as the test print.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@dpiTestLabelPrinter",
                "x-source": "app/Http/Controllers/SettingsController.php#L1419-L1476",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pos_settings",
                        "slug": "pos_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PosSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`{success, qz, printer, payload_base64, message}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "qz": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "printer": {
                                            "type": "string"
                                        },
                                        "payload_base64": {},
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "POS settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "POS settings not found."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/label_printer_test": {
            "post": {
                "operationId": "post_api_label_printer_test",
                "tags": [
                    "System Settings"
                ],
                "summary": "Print a test label",
                "description": "Builds a TSPL job for the configured label printer and either sends it directly (network mode) or returns it base64-encoded for QZ Tray (`qz: true`). Any `label_printer_*` field in the payload temporarily overrides the saved value so the form can test before saving. In raster mode supply the pre-rendered bitmaps in `rasters`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@testLabelPrinter",
                "x-source": "app/Http/Controllers/SettingsController.php#L1353-L1411",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pos_settings",
                        "slug": "pos_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PosSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "height_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Label height override.",
                                        "type": "number"
                                    },
                                    "offset_x_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "X offset override.",
                                        "type": "number"
                                    },
                                    "offset_y_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Y offset override.",
                                        "type": "number"
                                    },
                                    "printer_dpi": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "DPI override.",
                                        "type": "integer"
                                    },
                                    "rasters": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "string",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "string"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Base64 packed 1-bit-per-pixel row data."
                                                },
                                                "height": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer",
                                                        "min:1"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Bitmap height in dots."
                                                },
                                                "width_bytes": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer",
                                                        "min:1"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Bytes per row (width / 8, rounded up)."
                                                }
                                            },
                                            "required": [
                                                "data",
                                                "height",
                                                "width_bytes"
                                            ]
                                        },
                                        "minItems": 1,
                                        "maxItems": 10,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1",
                                            "max:10"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "1–10 monochrome bitmaps rendered by the browser (raster mode)."
                                    },
                                    "width_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Label width override.",
                                        "type": "number"
                                    }
                                },
                                "required": [
                                    "rasters"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success, qz, printer, payload_base64, message}` — when `qz` is true the client must hand `payload_base64` to QZ Tray.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "qz": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "printer": {
                                            "type": "string"
                                        },
                                        "payload_base64": {},
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "POS settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "POS settings not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/label_printer_test_design": {
            "get": {
                "operationId": "get_api_label_printer_test_design",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get label test design",
                "description": "Returns the design (dimensions, DPI, offsets, element positions) and a sample label record the settings page uses to render raster test prints in the browser before sending them via `POST /api/label_printer_test`. Query overrides let the form preview unsaved values.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@labelPrinterTestDesign",
                "x-source": "app/Http/Controllers/SettingsController.php#L1342-L1351",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pos_settings",
                        "slug": "pos_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PosSetting"
                ],
                "parameters": [
                    {
                        "name": "height_mm",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "number"
                        },
                        "description": "Label height override (mm)."
                    },
                    {
                        "name": "offset_x_mm",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "number"
                        },
                        "description": "Horizontal offset override."
                    },
                    {
                        "name": "offset_y_mm",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "number"
                        },
                        "description": "Vertical offset override."
                    },
                    {
                        "name": "printer_dpi",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "DPI override (203/300)."
                    },
                    {
                        "name": "width_mm",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "number"
                        },
                        "description": "Label width override (mm)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{design: {...}, label: {name, price, barcode, ...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "design": {},
                                        "label": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/languages": {
            "get": {
                "operationId": "get_api_languages",
                "tags": [
                    "Health & Utilities"
                ],
                "summary": "List available languages",
                "description": "Public list of the languages configured in Stocky, used by the language switcher on the login page and in the SPA header.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "LanguageController@load_language",
                "x-source": "app/Http/Controllers/LanguageController.php#L12-L18",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Language"
                ],
                "responses": {
                    "200": {
                        "description": "Array of language rows (`id`, `name`, `locale`, `is_rtl`/direction flags, `is_default`, `is_active`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/languages_setting": {
            "get": {
                "operationId": "get_api_languages_setting",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "List languages",
                "description": "All configured UI languages with `locale`, `name`, `flag` image, `is_default` and `is_active`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@index",
                "x-source": "app/Http/Controllers/LanguageController.php#L20-L25",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Language"
                ],
                "responses": {
                    "200": {
                        "description": "Array of language objects."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_languages_setting",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Create a language",
                "description": "Adds a language. Upload an optional flag image (PNG/JPG/SVG, max 2 MB) stored under `public/flags`. The locale must be unique. The new language starts with an empty catalogue; use `PUT /api/translations_setting/{locale}` to populate it (the UI copies English keys as placeholders).",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@store",
                "x-source": "app/Http/Controllers/LanguageController.php#L27-L56",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Language"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "flag": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:png,jpg,jpeg,svg",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Flag image file.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "locale": {
                                        "type": "string",
                                        "maxLength": 10,
                                        "x-unique": "languages",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:10",
                                            "unique:languages"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Locale code (max 10 chars, e.g. `fr`, `pt-BR`)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Display name (e.g. `Français`)."
                                    }
                                },
                                "required": [
                                    "locale",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "Created language object."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/languages_setting/set-default/{locale}": {
            "post": {
                "operationId": "post_api_languages_setting_set_default_locale",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Set default language by locale",
                "description": "Same as the ID variant but addressed by locale code. No-op if the locale is already default.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@setDefaultByLocale",
                "x-source": "app/Http/Controllers/LanguageController.php#L148-L174",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Language",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "en"
                        },
                        "description": "Locale code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, message, default_locale}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Default language set successfully."
                                        },
                                        "default_locale": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/languages_setting/{id}/set-active": {
            "post": {
                "operationId": "post_api_languages_setting_id_set_active",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Toggle language active",
                "description": "Flips `is_active`. Inactive languages are hidden from the language switcher but keep their translations.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@setLocaleActive",
                "x-source": "app/Http/Controllers/LanguageController.php#L176-L193",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Language"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Language ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, message, new_status}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Updated successfully."
                                        },
                                        "new_status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/languages_setting/{id}/set-default": {
            "post": {
                "operationId": "post_api_languages_setting_id_set_default",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Set default language by ID",
                "description": "Marks the language as default, unmarks all others and updates `default_language` in the global settings.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@setDefault",
                "x-source": "app/Http/Controllers/LanguageController.php#L119-L146",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Language",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Language ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, message, default_locale}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Default language set successfully."
                                        },
                                        "default_locale": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/languages_setting/{language}": {
            "delete": {
                "operationId": "delete_api_languages_setting_language",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Delete a language",
                "description": "Deletes the language and every translation row for its locale. Do not delete the default language.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@destroy",
                "x-source": "app/Http/Controllers/LanguageController.php#L106-L117",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Translate"
                ],
                "parameters": [
                    {
                        "name": "language",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Language ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_languages_setting_language",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Update a language",
                "description": "Renames a language, changes its locale code or replaces the flag image (the old file is deleted unless it is the placeholder). Send as multipart when uploading a flag.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@update",
                "x-source": "app/Http/Controllers/LanguageController.php#L58-L104",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "language",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Language ID."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "flag": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:png,jpg,jpeg,svg",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "New flag image.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "locale": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'required|string|max:10|unique:languages,locale,' . $language->id"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'required|string|max:10|unique:languages,locale,' . $language->id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Locale code (must remain unique)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Display name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true, language}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "language": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/leave": {
            "get": {
                "operationId": "get_api_leave",
                "tags": [
                    "Leaves"
                ],
                "summary": "List leaves",
                "description": "Paginated leaves joined with `employee_name`, `leave_type_title`, `company_name`, `department_name`. `search` matches employee, leave type, company or department. Prefix sort fields with `leaves.`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@index",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L18-L64",
                "x-route-name": "leave.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Leave"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`leaves[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "leaves": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_leave",
                "tags": [
                    "Leaves"
                ],
                "summary": "Create a leave request",
                "description": "`days` = inclusive number of days between the dates. If `days` exceeds the employee's `remaining_leave` the request is rejected (HTTP 200 with `isvalid: false`). When `status` is `approved` the balance is deducted immediately.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@store",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L82-L138",
                "x-route-name": "leave.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "LeaveType",
                    "Employee",
                    "Leave"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "attachment": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpeg,png,jpg,bmp,gif,svg",
                                        "maxLength": 2048,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpeg,png,jpg,bmp,gif,svg",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Optional image (jpeg/png/jpg/bmp/gif/svg, max 2 MB)."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last day (>= start)."
                                    },
                                    "half_day": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Half-day flag / note."
                                    },
                                    "leave_type_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Leave type."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason text."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First day."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`pending`, `approved` or `rejected`."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department_id",
                                    "employee_id",
                                    "end_date",
                                    "leave_type_id",
                                    "start_date",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true, isvalid: true}` or `{remaining_leave: \"remaining leaves are insufficient\", isvalid: false}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "remaining_leave": {
                                            "type": "string",
                                            "example": "remaining leaves are insufficient"
                                        },
                                        "isvalid": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/leave/create": {
            "get": {
                "operationId": "get_api_leave_create",
                "tags": [
                    "Leaves"
                ],
                "summary": "Create-form data for a leave",
                "description": "Lookup data for the leave form: companies, employees and leave types.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@create",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L66-L78",
                "x-route-name": "leave.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "LeaveType",
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]` and `leave_types[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "leave_types": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/leave/delete/by_selection": {
            "post": {
                "operationId": "post_api_leave_delete_by_selection",
                "tags": [
                    "Leaves"
                ],
                "summary": "Delete selected leaves",
                "description": "Bulk soft-delete of leave requests by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L279-L303",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "Leave"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Leave ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/leave/{leave}": {
            "delete": {
                "operationId": "delete_api_leave_leave",
                "tags": [
                    "Leaves"
                ],
                "summary": "Delete a leave",
                "description": "Soft-deletes the leave and removes its attachment file. The leave balance is **not** restored.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@destroy",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L256-L275",
                "x-route-name": "leave.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "Leave"
                ],
                "parameters": [
                    {
                        "name": "leave",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_leave_leave",
                "tags": [
                    "Leaves"
                ],
                "summary": "Get a leave (not implemented)",
                "description": "**Not implemented** — empty response; use the edit endpoint.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@show",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L142-L146",
                "x-route-name": "leave.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "leave",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_leave_leave",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Leaves"
                ],
                "summary": "Update a leave request",
                "description": "Re-validates the balance: the days of the previous approved version are first credited back, then the new period is checked and deducted again if approved. Send `attachment` only to replace the file.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@update",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L166-L252",
                "x-route-name": "leave.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "Leave",
                    "LeaveType",
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "leave",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "attachment": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpeg,png,jpg,bmp,gif,svg",
                                        "maxLength": 2048,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpeg,png,jpg,bmp,gif,svg",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read",
                                            "file"
                                        ],
                                        "description": "New image file."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last day."
                                    },
                                    "half_day": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Half-day flag."
                                    },
                                    "leave_type_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Leave type."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First day."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`pending`, `approved`, `rejected`."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department_id",
                                    "employee_id",
                                    "end_date",
                                    "leave_type_id",
                                    "start_date",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true, isvalid: true}` or `isvalid: false` when balance insufficient.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "remaining_leave": {
                                            "type": "string",
                                            "example": "remaining leaves are insufficient"
                                        },
                                        "isvalid": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_leave_leave",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Leaves"
                ],
                "summary": "Update a leave request",
                "description": "Re-validates the balance: the days of the previous approved version are first credited back, then the new period is checked and deducted again if approved. Send `attachment` only to replace the file.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@update",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L166-L252",
                "x-route-name": "leave.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "Leave",
                    "LeaveType",
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "leave",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "attachment": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpeg,png,jpg,bmp,gif,svg",
                                        "maxLength": 2048,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpeg,png,jpg,bmp,gif,svg",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read",
                                            "file"
                                        ],
                                        "description": "New image file."
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "department_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Department."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last day."
                                    },
                                    "half_day": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Half-day flag."
                                    },
                                    "leave_type_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Leave type."
                                    },
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First day."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`pending`, `approved`, `rejected`."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "department_id",
                                    "employee_id",
                                    "end_date",
                                    "leave_type_id",
                                    "start_date",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true, isvalid: true}` or `isvalid: false` when balance insufficient.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "remaining_leave": {
                                            "type": "string",
                                            "example": "remaining leaves are insufficient"
                                        },
                                        "isvalid": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/leave/{leave}/edit": {
            "get": {
                "operationId": "get_api_leave_leave_edit",
                "tags": [
                    "Leaves"
                ],
                "summary": "Edit-form data for a leave",
                "description": "The leave request with the lookups needed by the edit form.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveController@edit",
                "x-source": "app/Http/Controllers/hrm/LeaveController.php#L148-L162",
                "x-route-name": "leave.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "Leave",
                    "LeaveType",
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "leave",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`leave`, `companies[]`, `leave_types[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "leave": {},
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "leave_types": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/leave_type": {
            "get": {
                "operationId": "get_api_leave_type",
                "tags": [
                    "Leave Types"
                ],
                "summary": "List leave types",
                "description": "Paginated; `search` matches the title.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveTypeController@index",
                "x-source": "app/Http/Controllers/hrm/LeaveTypeController.php#L15-L48",
                "x-route-name": "leave_type.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "LeaveType"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`leave_types[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "leave_types": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_leave_type",
                "tags": [
                    "Leave Types"
                ],
                "summary": "Create a leave type",
                "description": "Creates a leave type (title, days allowed per year, paid/unpaid).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveTypeController@store",
                "x-source": "app/Http/Controllers/hrm/LeaveTypeController.php#L52-L65",
                "x-route-name": "leave_type.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "LeaveType"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/leave_type/delete/by_selection": {
            "post": {
                "operationId": "post_api_leave_type_delete_by_selection",
                "tags": [
                    "Leave Types"
                ],
                "summary": "Delete selected leave types",
                "description": "Bulk soft-delete of leave types by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveTypeController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/LeaveTypeController.php#L109-L122",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "LeaveType"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Leave type ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/leave_type/{leave_type}": {
            "delete": {
                "operationId": "delete_api_leave_type_leave_type",
                "tags": [
                    "Leave Types"
                ],
                "summary": "Delete a leave type",
                "description": "Soft-deletes a leave type.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveTypeController@destroy",
                "x-source": "app/Http/Controllers/hrm/LeaveTypeController.php#L96-L105",
                "x-route-name": "leave_type.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "LeaveType"
                ],
                "parameters": [
                    {
                        "name": "leave_type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave type id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_leave_type_leave_type",
                "tags": [
                    "Leave Types"
                ],
                "summary": "Get a leave type (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveTypeController@show",
                "x-source": "app/Http/Controllers/hrm/LeaveTypeController.php#L69-L73",
                "x-route-name": "leave_type.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "leave_type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave type id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_leave_type_leave_type",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Leave Types"
                ],
                "summary": "Update a leave type",
                "description": "Updates a leave type with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveTypeController@update",
                "x-source": "app/Http/Controllers/hrm/LeaveTypeController.php#L77-L92",
                "x-route-name": "leave_type.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "LeaveType"
                ],
                "parameters": [
                    {
                        "name": "leave_type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave type id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_leave_type_leave_type",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Leave Types"
                ],
                "summary": "Update a leave type",
                "description": "Updates a leave type with the same fields as creation.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\LeaveTypeController@update",
                "x-source": "app/Http/Controllers/hrm/LeaveTypeController.php#L77-L92",
                "x-route-name": "leave_type.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "leave",
                        "policy": "LeavePolicy"
                    }
                ],
                "x-models": [
                    "LeaveType"
                ],
                "parameters": [
                    {
                        "name": "leave_type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Leave type id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/loyalty/adjust": {
            "post": {
                "operationId": "post_api_loyalty_adjust",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Adjust a customer's points manually",
                "description": "Credits or debits points on a customer with an audit note. A debit larger than the balance is rejected. Returns the new balance.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@adjust",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L164-L184",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "integer",
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer id."
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reason, max 255."
                                    },
                                    "points": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Points to add or remove (> 0)."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "credit",
                                            "debit"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:credit,debit"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`credit` or `debit`."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "points",
                                    "type"
                                ]
                            },
                            "example": {
                                "client_id": 3,
                                "type": "credit",
                                "points": 100,
                                "note": "Goodwill for late delivery"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and new `balance`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "balance": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "balance": 220
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/clients": {
            "get": {
                "operationId": "get_api_loyalty_clients",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Search customers for the adjust dialog",
                "description": "Up to 20 customers matching `search` on name or email, with their current `points`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@searchClients",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L234-L243",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name or email fragment."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`clients[]` (`id, name, email, points`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/pos/redeem": {
            "post": {
                "operationId": "post_api_loyalty_pos_redeem",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Redeem a reward at POS",
                "description": "Spends the customer's points on a reward: checks eligibility, balance, stock and per-customer limit, then issues a redemption with a `code` (channel `pos`). The response returns the `reward_type`, the `code` to apply to the ticket, and the remaining `points`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@posRedeem",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L205-L231",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "LoyaltyReward"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "integer",
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer id."
                                    },
                                    "reward_id": {
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reward id."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "reward_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Redemption result.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "reward_type": {},
                                        "code": {},
                                        "points": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "reward_type": "voucher",
                                    "code": "LR-7F3K9Q",
                                    "points": 20
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Reward not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/pos/rewards": {
            "get": {
                "operationId": "get_api_loyalty_pos_rewards",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Get rewards and balance for POS",
                "description": "For the POS reward picker: the customer's `points` balance, whether they are `eligible`, and the currently available `rewards[]`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@posRewards",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L189-L202",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer id (omit for a walk-in customer → points 0)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`points`, `eligible`, `rewards[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "points": {},
                                        "eligible": {},
                                        "rewards": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/redemptions": {
            "get": {
                "operationId": "get_api_loyalty_redemptions",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "List redemptions",
                "description": "Paginated redemptions (Laravel paginator, `per_page` default 15): `id, client_name, reward_name, reward_type, points_spent, status (issued|fulfilled|cancelled), channel (pos|store), code, created_at`. `search` matches reward name, code or customer name.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@redemptions",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L98-L131",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "LoyaltyRewardRedemption"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Rows per page (default 15)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`issued`, `fulfilled` or `cancelled`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `meta {total, page, pages}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/redemptions/{id}/cancel": {
            "post": {
                "operationId": "post_api_loyalty_redemptions_id_cancel",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Cancel a redemption",
                "description": "Cancels an issued redemption and refunds the points to the customer (recorded as a point transaction).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@cancel",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L149-L160",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-models": [
                    "LoyaltyRewardRedemption"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Redemption id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Cannot be cancelled (already fulfilled/cancelled)."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/redemptions/{id}/fulfill": {
            "post": {
                "operationId": "post_api_loyalty_redemptions_id_fulfill",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Mark a redemption as fulfilled",
                "description": "Marks an `issued` redemption as handed over (`fulfilled`, with user and timestamp). Other statuses return `422`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@fulfill",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L133-L147",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-models": [
                    "LoyaltyRewardRedemption"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Redemption id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Redemption is not pending.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/rewards": {
            "get": {
                "operationId": "get_api_loyalty_rewards",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "List rewards",
                "description": "All rewards ordered by `sort_order`, each with `redemptions_count` and its presented fields (`id, name, description, type, points_cost, value, product_id, product_name, stock, per_customer_limit, active, image, sort_order`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@index",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L25-L40",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-models": [
                    "LoyaltyReward"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on reward name."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`gift_card`, `voucher` or `product`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rewards[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rewards": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_loyalty_rewards",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Create a reward",
                "description": "Creates a reward. `value` is the monetary value for gift cards / vouchers; `product_id` is required for `type = product`. Returns HTTP **201**.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@store",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L42-L49",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-models": [
                    "LoyaltyReward"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "`1` active / `0` hidden.",
                                        "type": "boolean"
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description, max 500."
                                    },
                                    "image": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Image file name."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reward name, max 150."
                                    },
                                    "per_customer_limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Max redemptions per customer."
                                    },
                                    "points_cost": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Points needed to redeem (> 0)."
                                    },
                                    "product_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "products,id",
                                        "x-conditional": [
                                            "required_if:type,product"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "required_if:type,product",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product given away (type `product`)."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Display order."
                                    },
                                    "stock": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of redemptions available, or `null` for unlimited."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-enum-source": "\\App\\Models\\LoyaltyReward::TYPES",
                                        "x-laravel-rules": [
                                            "required",
                                            "in:\\App\\Models\\LoyaltyReward::TYPES"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`gift_card`, `voucher` or `product`."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Monetary value of the gift card / voucher."
                                    }
                                },
                                "required": [
                                    "name",
                                    "points_cost",
                                    "type"
                                ]
                            },
                            "example": {
                                "name": "5 € voucher",
                                "type": "voucher",
                                "points_cost": 500,
                                "value": 5,
                                "active": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and new `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/loyalty/rewards/{id}": {
            "delete": {
                "operationId": "delete_api_loyalty_rewards_id",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Delete a reward",
                "description": "Deletes the reward; past redemptions keep their `reward_name`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@destroy",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L60-L66",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-models": [
                    "LoyaltyReward"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Reward id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_loyalty_rewards_id",
                "tags": [
                    "Loyalty Rewards"
                ],
                "summary": "Update a reward",
                "description": "Replaces the reward's attributes (same validation as create).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "LoyaltyRewardController@update",
                "x-source": "app/Http/Controllers/LoyaltyRewardController.php#L51-L58",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "loyalty_rewards",
                        "policy": "LoyaltyRewardPolicy"
                    }
                ],
                "x-models": [
                    "LoyaltyReward"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Reward id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Active flag.",
                                        "type": "boolean"
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "image": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Image."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "per_customer_limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-customer cap."
                                    },
                                    "points_cost": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Points cost."
                                    },
                                    "product_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "products,id",
                                        "x-conditional": [
                                            "required_if:type,product"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "required_if:type,product",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product id (type product)."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sort order."
                                    },
                                    "stock": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Remaining stock."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-enum-source": "\\App\\Models\\LoyaltyReward::TYPES",
                                        "x-laravel-rules": [
                                            "required",
                                            "in:\\App\\Models\\LoyaltyReward::TYPES"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reward type."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Monetary value."
                                    }
                                },
                                "required": [
                                    "name",
                                    "points_cost",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mailchimp/lists": {
            "get": {
                "operationId": "get_api_mailchimp_lists",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "List audiences",
                "description": "The account's audiences, for the settings page picker.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@lists",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L93-L105",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "x-models": [
                    "MailchimpSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`lists[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "lists": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "API key missing / error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mailchimp/logs": {
            "delete": {
                "operationId": "delete_api_mailchimp_logs",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "Clear Mailchimp logs",
                "description": "Clears the Mailchimp sync log.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@clearLogs",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L142-L149",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "x-models": [
                    "MailchimpLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_mailchimp_logs",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "Mailchimp logs",
                "description": "Paginated Mailchimp sync log entries.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@logs",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L130-L140",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MailchimpLog"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Level."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mailchimp/settings": {
            "get": {
                "operationId": "get_api_mailchimp_settings",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "Get Mailchimp settings",
                "description": "Current Mailchimp settings (API key masked, audience/list ID, server prefix, sync options).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@settings",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L18-L35",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "x-models": [
                    "MailchimpSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `configured`, `ready`, `has_api_key`, `list_id`, `list_name`, `double_opt_in`, `auto_sync`, `last_sync_at`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "configured": {},
                                        "ready": {},
                                        "has_api_key": {},
                                        "list_id": {},
                                        "list_name": {},
                                        "double_opt_in": {
                                            "type": "boolean"
                                        },
                                        "auto_sync": {
                                            "type": "boolean"
                                        },
                                        "last_sync_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_mailchimp_settings",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "Save Mailchimp settings",
                "description": "Saves the Mailchimp API key, audience ID and sync options.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@saveSettings",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L37-L69",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "x-models": [
                    "MailchimpSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "api_key": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "API key (write-only)."
                                    },
                                    "auto_sync": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Sync new customers automatically."
                                    },
                                    "double_opt_in": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Send opt-in email."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "list_id": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Audience id."
                                    },
                                    "list_name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Audience name."
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `ready`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "ready": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mailchimp/stats": {
            "get": {
                "operationId": "get_api_mailchimp_stats",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "Sync statistics",
                "description": "Counters: customers synced, audience size, last sync.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@stats",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L107-L112",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Counts.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mailchimp/sync/customers": {
            "post": {
                "operationId": "post_api_mailchimp_sync_customers",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "Push customers to the audience",
                "description": "Adds or updates every customer with an email address as a member of the configured audience (merge fields: name, phone).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@syncCustomers",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L114-L128",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "x-models": [
                    "MailchimpSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call (default 50).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `pushed`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not ready / error."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mailchimp/test-connection": {
            "post": {
                "operationId": "post_api_mailchimp_test_connection",
                "tags": [
                    "Mailchimp"
                ],
                "summary": "Test the Mailchimp connection",
                "description": "Pings the Mailchimp API with the stored key and returns the account name on success.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\MailchimpSettingsController@testConnection",
                "x-source": "app/Http/Controllers/Integrations/MailchimpSettingsController.php#L71-L90",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "MailchimpSettingPolicy"
                    }
                ],
                "x-models": [
                    "MailchimpSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not configured / failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Add the API key first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/activity_logs": {
            "get": {
                "operationId": "get_api_marketing_activity_logs",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Marketing activity log",
                "description": "Last 100 actions (campaign/segment/template/settings changes) with the acting user.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@activity_logs",
                "x-source": "app/Http/Controllers/MarketingController.php#L652-L660",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "MarketingActivityLog"
                ],
                "responses": {
                    "200": {
                        "description": "`logs[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "logs": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Error"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/campaigns": {
            "get": {
                "operationId": "get_api_marketing_campaigns",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "List campaigns",
                "description": "Paginated; `search` matches title or description.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_index",
                "x-source": "app/Http/Controllers/MarketingController.php#L123-L161",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MarketingCampaign"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`draft`, `scheduled`, `sending`, `sent`, `failed`, `cancelled`."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`sms`, `email`, `whatsapp`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`campaigns[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "campaigns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_marketing_campaigns",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Create a campaign",
                "description": "Multipart (optional `attachment`). Status is `scheduled` when `send_immediately` is false and `scheduled_at` is set, otherwise `draft`; use *Send a campaign* to dispatch. Audience is either `all_customers` or a `segment_id`.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_store",
                "x-source": "app/Http/Controllers/MarketingController.php#L183-L232",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "all_customers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Send to every customer.",
                                        "type": "boolean"
                                    },
                                    "attachment": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "File attached to emails."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Internal description."
                                    },
                                    "message_content": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Message body (placeholders like `{name}` are substituted)."
                                    },
                                    "scheduled_at": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Scheduled send time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "segment_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Target segment."
                                    },
                                    "send_immediately": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Send now when dispatched (default true).",
                                        "type": "boolean"
                                    },
                                    "subject": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email subject."
                                    },
                                    "template_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Template used to prefill the content."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sms",
                                            "email",
                                            "whatsapp"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sms,email,whatsapp"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`sms`, `email` or `whatsapp`."
                                    }
                                },
                                "required": [
                                    "message_content",
                                    "title",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/campaigns/delete/by_selection": {
            "post": {
                "operationId": "post_api_marketing_campaigns_delete_by_selection",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Delete selected campaigns",
                "description": "Bulk delete of campaigns by `selectedIds`. Sent campaigns keep their delivery log.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_delete_by_selection",
                "x-source": "app/Http/Controllers/MarketingController.php#L338-L353",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Campaign ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/campaigns/{id}": {
            "delete": {
                "operationId": "delete_api_marketing_campaigns_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Delete a campaign",
                "description": "Deletes a campaign. Campaigns currently sending cannot be deleted.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_destroy",
                "x-source": "app/Http/Controllers/MarketingController.php#L326-L336",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Campaign id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_marketing_campaigns_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Get a campaign",
                "description": "Campaign with its segment and template, `recipient_stats` (count per delivery status) and the last 200 `recipients`.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_show",
                "x-source": "app/Http/Controllers/MarketingController.php#L163-L181",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign",
                    "MarketingCampaignRecipient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Campaign id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`campaign`, `recipient_stats`, `recipients[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "campaign": {},
                                        "recipient_stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recipients": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_marketing_campaigns_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Update a campaign (multipart)",
                "description": "Same fields as create. Campaigns in `sending` / `sent` cannot be edited (`422`).",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_update",
                "x-source": "app/Http/Controllers/MarketingController.php#L234-L289",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Campaign id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "all_customers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Send to every customer.",
                                        "type": "boolean"
                                    },
                                    "attachment": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "File attached to emails."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Internal description."
                                    },
                                    "message_content": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Message body (placeholders like `{name}` are substituted)."
                                    },
                                    "scheduled_at": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Scheduled send time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "segment_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Target segment."
                                    },
                                    "send_immediately": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Send now when dispatched (default true).",
                                        "type": "boolean"
                                    },
                                    "subject": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email subject."
                                    },
                                    "template_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Template used to prefill the content."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sms",
                                            "email",
                                            "whatsapp"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sms,email,whatsapp"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`sms`, `email` or `whatsapp`."
                                    }
                                },
                                "required": [
                                    "message_content",
                                    "title",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_marketing_campaigns_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Update a campaign",
                "description": "Same as the POST variant (use POST when uploading an attachment).",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_update",
                "x-source": "app/Http/Controllers/MarketingController.php#L234-L289",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Campaign id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "all_customers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Send to every customer.",
                                        "type": "boolean"
                                    },
                                    "attachment": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "File attached to emails."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Internal description."
                                    },
                                    "message_content": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Message body (placeholders like `{name}` are substituted)."
                                    },
                                    "scheduled_at": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Scheduled send time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "segment_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Target segment."
                                    },
                                    "send_immediately": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Send now when dispatched (default true).",
                                        "type": "boolean"
                                    },
                                    "subject": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email subject."
                                    },
                                    "template_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Template used to prefill the content."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sms",
                                            "email",
                                            "whatsapp"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sms,email,whatsapp"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`sms`, `email` or `whatsapp`."
                                    }
                                },
                                "required": [
                                    "message_content",
                                    "title",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/campaigns/{id}/send": {
            "post": {
                "operationId": "post_api_marketing_campaigns_id_send",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Send a campaign",
                "description": "Marks the campaign `sending` and queues the send job. Refused while already sending.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_send",
                "x-source": "app/Http/Controllers/MarketingController.php#L308-L324",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Campaign id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Already sending.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Campaign is already sending."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/campaigns/{id}/status": {
            "put": {
                "operationId": "put_api_marketing_campaigns_id_status",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Set campaign status",
                "description": "Changes the campaign status: `draft`, `scheduled`, `sending`, `paused`, `sent`, `cancelled`. Moving to `scheduled` requires `scheduled_at`; `sending` queues the messages immediately.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@campaigns_update_status",
                "x-source": "app/Http/Controllers/MarketingController.php#L291-L303",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "marketing_campaigns",
                        "policy": "MarketingCampaignPolicy"
                    }
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Campaign id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "scheduled",
                                            "sending",
                                            "sent",
                                            "failed",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:draft,scheduled,sending,sent,failed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New status."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/dashboard": {
            "get": {
                "operationId": "get_api_marketing_dashboard",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Marketing dashboard",
                "description": "Totals (`total_campaigns`, `total_messages`, `total_sms`, `total_emails`, `total_whatsapp`, `failed_messages`), `by_status`, `by_type`, 6-month `monthly` volume per channel and `recent` campaigns.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@dashboard",
                "x-source": "app/Http/Controllers/MarketingController.php#L72-L119",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total_campaigns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total_messages": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total_emails": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total_whatsapp": {},
                                        "total_sms": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "failed_messages": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_status": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_type": {},
                                        "monthly": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recent": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Error"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/reports": {
            "get": {
                "operationId": "get_api_marketing_reports",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Campaign performance report",
                "description": "Campaigns created in the period (default last 3 months) with `summary` (`total_campaigns, sent, delivered, failed, pending, recipients`) and `by_type` breakdown.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@reports",
                "x-source": "app/Http/Controllers/MarketingController.php#L612-L648",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "MarketingCampaign"
                ],
                "parameters": [
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`campaigns[]`, `summary`, `by_type`, `from`, `to`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "type": {},
                                        "campaigns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sent": {
                                            "type": "integer"
                                        },
                                        "failed": {
                                            "type": "integer"
                                        },
                                        "recipients": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "by_type": {},
                                        "from": {
                                            "type": "string"
                                        },
                                        "to": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Error"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/segments": {
            "get": {
                "operationId": "get_api_marketing_segments",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "List segments",
                "description": "Paginated; `search` matches the name.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@segments_index",
                "x-source": "app/Http/Controllers/MarketingController.php#L357-L380",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_segments",
                        "policy": "MarketingSegmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MarketingSegment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`segments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "segments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_marketing_segments",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Create a segment",
                "description": "Stores the filters and the resolved `customers_count`.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@segments_store",
                "x-source": "app/Http/Controllers/MarketingController.php#L391-L412",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "marketing_segments",
                        "policy": "MarketingSegmentPolicy"
                    }
                ],
                "x-models": [
                    "MarketingSegment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "all_customers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "All customers.",
                                        "type": "boolean"
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "filters": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Filter rules.",
                                        "type": "array",
                                        "items": {}
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/segments/preview": {
            "post": {
                "operationId": "post_api_marketing_segments_preview",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Preview a segment",
                "description": "Counts customers matching the filters and returns a sample of 10.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@segments_preview",
                "x-source": "app/Http/Controllers/MarketingController.php#L450-L462",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_segments",
                        "policy": "MarketingSegmentPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "all_customers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ignore filters and take everyone.",
                                        "type": "boolean"
                                    },
                                    "filters": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Filter rules (e.g. `[{field: \"city\", operator: \"=\", value: \"Casablanca\"}]`).",
                                        "type": "array",
                                        "items": {}
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`count` and `sample[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        },
                                        "sample": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/segments/{id}": {
            "delete": {
                "operationId": "delete_api_marketing_segments_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Delete a segment",
                "description": "Deletes a customer segment. Campaigns that used it keep their recipient snapshot.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@segments_destroy",
                "x-source": "app/Http/Controllers/MarketingController.php#L437-L445",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "marketing_segments",
                        "policy": "MarketingSegmentPolicy"
                    }
                ],
                "x-models": [
                    "MarketingSegment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Segment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_marketing_segments_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Update a segment",
                "description": "Updates a segment's name and filter conditions; the member count is recomputed.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@segments_update",
                "x-source": "app/Http/Controllers/MarketingController.php#L414-L435",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "marketing_segments",
                        "policy": "MarketingSegmentPolicy"
                    }
                ],
                "x-models": [
                    "MarketingSegment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Segment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "all_customers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "All customers.",
                                        "type": "boolean"
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "filters": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Filter rules.",
                                        "type": "array",
                                        "items": {}
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/segments_all": {
            "get": {
                "operationId": "get_api_marketing_segments_all",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "All segments (lookup)",
                "description": "All segments as `{id, name, customers_count}` for select inputs.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@segments_all",
                "x-source": "app/Http/Controllers/MarketingController.php#L382-L389",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_segments",
                        "policy": "MarketingSegmentPolicy"
                    }
                ],
                "x-models": [
                    "MarketingSegment"
                ],
                "responses": {
                    "200": {
                        "description": "`segments[] {id, name, all_customers, customers_count}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "segments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/settings": {
            "get": {
                "operationId": "get_api_marketing_settings",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Get marketing settings",
                "description": "Marketing module settings: default sender, channels enabled (email/SMS/WhatsApp), sending rate and unsubscribe text.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@settings_show",
                "x-source": "app/Http/Controllers/MarketingController.php#L582-L587",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_settings",
                        "policy": "MarketingSettingPolicy"
                    }
                ],
                "x-models": [
                    "MarketingSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`settings` (channel toggles, provider config, sender names, `scheduling_enabled`, `batch_size`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_marketing_settings",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Save marketing settings",
                "description": "Generic HTTP gateway configuration for SMS and WhatsApp: the message is sent to `*_api_url` with `*_http_method`, placing the phone number in `*_to_field` and the text in `*_message_field`, plus `*_extra_params` (JSON) merged into the request.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@settings_update",
                "x-source": "app/Http/Controllers/MarketingController.php#L589-L608",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "marketing_settings",
                        "policy": "MarketingSettingPolicy"
                    }
                ],
                "x-models": [
                    "MarketingSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Recipients per batch.",
                                        "type": "integer"
                                    },
                                    "default_sender_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default sender."
                                    },
                                    "email_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable email."
                                    },
                                    "email_from_address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "From address."
                                    },
                                    "email_from_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "From name."
                                    },
                                    "scheduling_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow scheduled campaigns."
                                    },
                                    "sms_api_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "API key."
                                    },
                                    "sms_api_secret": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "API secret."
                                    },
                                    "sms_api_url": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Gateway URL."
                                    },
                                    "sms_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable SMS."
                                    },
                                    "sms_extra_params": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Extra params (JSON)."
                                    },
                                    "sms_http_method": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`GET` or `POST`."
                                    },
                                    "sms_message_field": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Field name for the message."
                                    },
                                    "sms_provider": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Provider label."
                                    },
                                    "sms_sender_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sender id / name.",
                                        "type": "string"
                                    },
                                    "sms_to_field": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Field name for the recipient."
                                    },
                                    "whatsapp_api_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "API key."
                                    },
                                    "whatsapp_api_url": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Gateway URL."
                                    },
                                    "whatsapp_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable WhatsApp."
                                    },
                                    "whatsapp_extra_params": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Extra params (JSON)."
                                    },
                                    "whatsapp_http_method": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "HTTP method."
                                    },
                                    "whatsapp_message_field": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Message field."
                                    },
                                    "whatsapp_phone_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number id.",
                                        "type": "string"
                                    },
                                    "whatsapp_provider": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Provider label."
                                    },
                                    "whatsapp_to_field": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Recipient field."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/templates": {
            "get": {
                "operationId": "get_api_marketing_templates",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "List templates",
                "description": "Paginated message templates with type (email/SMS/WhatsApp), subject and preview.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@templates_index",
                "x-source": "app/Http/Controllers/MarketingController.php#L466-L492",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_templates",
                        "policy": "MarketingTemplatePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MarketingTemplate"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`sms`, `email`, `whatsapp`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`templates[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "templates": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_marketing_templates",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Create a template",
                "description": "Creates a message template (name, type, subject, content with `{customer_name}`-style placeholders).",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@templates_store",
                "x-source": "app/Http/Controllers/MarketingController.php#L507-L529",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "marketing_templates",
                        "policy": "MarketingTemplatePolicy"
                    }
                ],
                "x-models": [
                    "MarketingTemplate"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free-text category."
                                    },
                                    "content": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Body with placeholders."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "subject": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email subject."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sms",
                                            "email",
                                            "whatsapp"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sms,email,whatsapp"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Channel."
                                    }
                                },
                                "required": [
                                    "content",
                                    "name",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/templates/{id}": {
            "delete": {
                "operationId": "delete_api_marketing_templates_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Delete a template",
                "description": "Deletes a template.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@templates_destroy",
                "x-source": "app/Http/Controllers/MarketingController.php#L570-L578",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "marketing_templates",
                        "policy": "MarketingTemplatePolicy"
                    }
                ],
                "x-models": [
                    "MarketingTemplate"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_marketing_templates_id",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Update a template",
                "description": "Updates a template with the same fields as creation.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@templates_update",
                "x-source": "app/Http/Controllers/MarketingController.php#L531-L553",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "marketing_templates",
                        "policy": "MarketingTemplatePolicy"
                    }
                ],
                "x-models": [
                    "MarketingTemplate"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Category."
                                    },
                                    "content": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Body."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "subject": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Subject."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sms",
                                            "email",
                                            "whatsapp"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:sms,email,whatsapp"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Channel."
                                    }
                                },
                                "required": [
                                    "content",
                                    "name",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/templates/{id}/duplicate": {
            "post": {
                "operationId": "post_api_marketing_templates_id_duplicate",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "Duplicate a template",
                "description": "Creates a copy of the template named `<name> (copy)` and returns it.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@templates_duplicate",
                "x-source": "app/Http/Controllers/MarketingController.php#L555-L568",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "marketing_templates",
                        "policy": "MarketingTemplatePolicy"
                    }
                ],
                "x-models": [
                    "MarketingTemplate"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Template id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and new `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/marketing/templates_all": {
            "get": {
                "operationId": "get_api_marketing_templates_all",
                "tags": [
                    "Marketing Campaigns"
                ],
                "summary": "All templates (lookup)",
                "description": "All templates as `{id, name, type}` for select inputs.",
                "x-section": "Marketing",
                "x-surface": "admin",
                "x-controller": "MarketingController@templates_all",
                "x-source": "app/Http/Controllers/MarketingController.php#L494-L505",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "marketing_templates",
                        "policy": "MarketingTemplatePolicy"
                    }
                ],
                "x-models": [
                    "MarketingTemplate"
                ],
                "parameters": [
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Channel filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`templates[] {id, name, type, subject, content}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "templates": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/attachments": {
            "post": {
                "operationId": "post_api_meeting_attachments",
                "tags": [
                    "Meetings"
                ],
                "summary": "Upload a meeting attachment",
                "description": "Uploads a file (multipart `file`) to a meeting (`meeting_id`).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@attachments_store",
                "x-source": "app/Http/Controllers/MeetingController.php#L452-L476",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "MeetingAttachment"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "maxLength": 10240,
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "max:10240"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "File, max 10 MB."
                                    },
                                    "meeting_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "meetings,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:meetings,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Meeting."
                                    }
                                },
                                "required": [
                                    "file",
                                    "meeting_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/attachments/{id}": {
            "delete": {
                "operationId": "delete_api_meeting_attachments_id",
                "tags": [
                    "Meetings"
                ],
                "summary": "Delete a meeting attachment",
                "description": "Deletes a meeting attachment and its file.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@attachments_destroy",
                "x-source": "app/Http/Controllers/MeetingController.php#L478-L494",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "MeetingAttachment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Attachment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/calendar": {
            "get": {
                "operationId": "get_api_meeting_calendar",
                "tags": [
                    "Meetings"
                ],
                "summary": "Calendar feed",
                "description": "Compact meeting rows (`id, title, meeting_date, start_time, end_time, type, status`) for the date range.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@calendar",
                "x-source": "app/Http/Controllers/MeetingController.php#L136-L154",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date from."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`meetings[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "meetings": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/dashboard": {
            "get": {
                "operationId": "get_api_meeting_dashboard",
                "tags": [
                    "Meetings"
                ],
                "summary": "Meetings dashboard",
                "description": "`stats` (total, upcoming, completed, ongoing, cancelled, today), next 10 `upcoming_meetings` with participant counts, `by_status` and `by_type` counts.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@dashboard",
                "x-source": "app/Http/Controllers/MeetingController.php#L93-L132",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "upcoming_meetings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_status": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_type": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/meetings": {
            "get": {
                "operationId": "get_api_meeting_meetings",
                "tags": [
                    "Meetings"
                ],
                "summary": "List meetings",
                "description": "Paginated meetings with organizer and `participants_count`. `search` matches title, description or location.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_index",
                "x-source": "app/Http/Controllers/MeetingController.php#L158-L207",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Meeting"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Meeting date from."
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Meeting date to."
                    },
                    {
                        "name": "organizer_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Organizer user id."
                    },
                    {
                        "name": "participant_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only meetings this user is invited to."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`scheduled`, `ongoing`, `completed`, `cancelled`."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`physical` or `online`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`meetings[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "meetings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_meeting_meetings",
                "tags": [
                    "Meetings"
                ],
                "summary": "Create a meeting",
                "description": "Creates the meeting and its participant rows. `organizer_id` defaults to the caller, `status` to `scheduled`, `reminder_minutes` to 30.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_store",
                "x-source": "app/Http/Controllers/MeetingController.php#L234-L269",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "agenda": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Agenda text."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_time": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "End time."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Room / address (physical)."
                                    },
                                    "meeting_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "meeting_link": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Join URL (online)."
                                    },
                                    "organizer_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Organizer user id."
                                    },
                                    "participants": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "User ids to invite.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "platform": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "e.g. `zoom`, `meet`, `teams` (online)."
                                    },
                                    "reminder_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reminder lead time in minutes.",
                                        "type": "integer"
                                    },
                                    "start_time": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start time `HH:MM`."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Initial status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 255)."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "physical",
                                            "online"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:physical,online"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`physical` or `online`."
                                    }
                                },
                                "required": [
                                    "meeting_date",
                                    "start_time",
                                    "title",
                                    "type"
                                ]
                            },
                            "example": {
                                "title": "Q4 planning",
                                "meeting_date": "2026-09-15",
                                "start_time": "10:00",
                                "end_time": "11:30",
                                "type": "online",
                                "platform": "meet",
                                "meeting_link": "https://meet.google.com/abc-defg",
                                "reminder_minutes": 15,
                                "participants": [
                                    2,
                                    5,
                                    8
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and new `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/meetings/delete/by_selection": {
            "post": {
                "operationId": "post_api_meeting_meetings_delete_by_selection",
                "tags": [
                    "Meetings"
                ],
                "summary": "Delete selected meetings",
                "description": "Bulk delete of meetings by `selectedIds`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_delete_by_selection",
                "x-source": "app/Http/Controllers/MeetingController.php#L332-L341",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Meeting ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/meetings/{id}": {
            "delete": {
                "operationId": "delete_api_meeting_meetings_id",
                "tags": [
                    "Meetings"
                ],
                "summary": "Delete a meeting",
                "description": "Deletes a meeting with its notes and attachments.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_destroy",
                "x-source": "app/Http/Controllers/MeetingController.php#L323-L330",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Meeting id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_meeting_meetings_id",
                "tags": [
                    "Meetings"
                ],
                "summary": "Get a meeting",
                "description": "Meeting with organizer, participants (with user), notes (with assignee), attachments and activity `logs` (newest first).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_show",
                "x-source": "app/Http/Controllers/MeetingController.php#L216-L232",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Meeting id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`meeting`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "meeting": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_meeting_meetings_id",
                "tags": [
                    "Meetings"
                ],
                "summary": "Update a meeting",
                "description": "Updates the fields sent and re-syncs `participants` when provided.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_update",
                "x-source": "app/Http/Controllers/MeetingController.php#L271-L307",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Meeting id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "agenda": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Agenda."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_time": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location."
                                    },
                                    "meeting_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "meeting_link": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Link."
                                    },
                                    "organizer_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Organizer."
                                    },
                                    "participants": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "User ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "platform": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Platform."
                                    },
                                    "reminder_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reminder minutes.",
                                        "type": "integer"
                                    },
                                    "start_time": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "physical",
                                            "online"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:physical,online"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    }
                                },
                                "required": [
                                    "meeting_date",
                                    "start_time",
                                    "title",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/meetings/{id}/attendance": {
            "post": {
                "operationId": "post_api_meeting_meetings_id_attendance",
                "tags": [
                    "Meetings"
                ],
                "summary": "Record attendance",
                "description": "Sets `attendance_status` for each participant row. Requires `meeting_attendance`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@attendance_update",
                "x-source": "app/Http/Controllers/MeetingController.php#L370-L391",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "Meeting",
                    "MeetingParticipant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Meeting id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "attendance": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "attendance_status": {
                                                    "x-inferred": true,
                                                    "type": "string",
                                                    "enum": [
                                                        "pending",
                                                        "present",
                                                        "absent",
                                                        "late"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "in:pending,present,absent,late"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`pending`, `present`, `absent`, `late`."
                                                },
                                                "id": {
                                                    "x-inferred": true,
                                                    "type": "integer",
                                                    "x-exists": "meeting_participants,id",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "exists:meeting_participants,id"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Participant row id."
                                                }
                                            },
                                            "required": [
                                                "attendance_status",
                                                "id"
                                            ]
                                        },
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "List of participant updates."
                                    }
                                },
                                "required": [
                                    "attendance"
                                ]
                            },
                            "example": {
                                "attendance": [
                                    {
                                        "id": 41,
                                        "attendance_status": "present"
                                    },
                                    {
                                        "id": 42,
                                        "attendance_status": "late"
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Error"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/meetings/{id}/invitations": {
            "post": {
                "operationId": "post_api_meeting_meetings_id_invitations",
                "tags": [
                    "Meetings"
                ],
                "summary": "Send invitations",
                "description": "Sends an in-app/mail notification to every participant with a user account and marks them notified.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_send_invitations",
                "x-source": "app/Http/Controllers/MeetingController.php#L345-L366",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Meeting id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and number `sent`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "sent": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/meetings/{id}/status": {
            "put": {
                "operationId": "put_api_meeting_meetings_id_status",
                "tags": [
                    "Meetings"
                ],
                "summary": "Change meeting status",
                "description": "Sets the meeting status: `scheduled`, `in_progress`, `completed` or `cancelled`. Completing a meeting records the end time.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_update_status",
                "x-source": "app/Http/Controllers/MeetingController.php#L309-L321",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "Meeting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Meeting id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "scheduled",
                                            "ongoing",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:scheduled,ongoing,completed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`scheduled`, `ongoing`, `completed`, `cancelled`."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/meetings_all": {
            "get": {
                "operationId": "get_api_meeting_meetings_all",
                "tags": [
                    "Meetings"
                ],
                "summary": "List all meetings (lookup)",
                "description": "`{id, title, meeting_date, status}` newest first.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@meetings_all",
                "x-source": "app/Http/Controllers/MeetingController.php#L209-L214",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "Meeting"
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/notes": {
            "post": {
                "operationId": "post_api_meeting_notes",
                "tags": [
                    "Meetings"
                ],
                "summary": "Add a note / decision / action item",
                "description": "Adds an entry to the meeting minutes: `type` is `note`, `decision` or `action` (action items take an assignee and due date).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@notes_store",
                "x-source": "app/Http/Controllers/MeetingController.php#L395-L418",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "MeetingNote"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "User id responsible (action items).",
                                        "type": "integer"
                                    },
                                    "content": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Text."
                                    },
                                    "due_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Due date (action items)."
                                    },
                                    "meeting_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "meetings,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:meetings,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Meeting."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`open` (default), `done`."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "note",
                                            "decision",
                                            "action_item"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:note,decision,action_item"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`note`, `decision` or `action_item`."
                                    }
                                },
                                "required": [
                                    "content",
                                    "meeting_id",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/notes/{id}": {
            "delete": {
                "operationId": "delete_api_meeting_notes_id",
                "tags": [
                    "Meetings"
                ],
                "summary": "Delete a note",
                "description": "Deletes a minutes entry.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@notes_destroy",
                "x-source": "app/Http/Controllers/MeetingController.php#L437-L448",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "MeetingNote"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Note id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_meeting_notes_id",
                "tags": [
                    "Meetings"
                ],
                "summary": "Update a note",
                "description": "Updates a minutes entry (content, type, assignee, due date, done flag).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@notes_update",
                "x-source": "app/Http/Controllers/MeetingController.php#L420-L435",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "meeting",
                        "policy": "MeetingPolicy"
                    }
                ],
                "x-models": [
                    "MeetingNote"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Note id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "User id.",
                                        "type": "integer"
                                    },
                                    "content": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Text."
                                    },
                                    "due_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "note",
                                            "decision",
                                            "action_item"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:note,decision,action_item"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    }
                                },
                                "required": [
                                    "content",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/meeting/reports": {
            "get": {
                "operationId": "get_api_meeting_reports",
                "tags": [
                    "Meetings"
                ],
                "summary": "Meetings report",
                "description": "`summary` (total, upcoming, completed, cancelled), `by_status`, `by_type`, `monthly_trend`, `attendance` counts per status, `attendance_rate` and `top_organizers` for the period.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "MeetingController@reports",
                "x-source": "app/Http/Controllers/MeetingController.php#L498-L571",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "Meeting",
                    "MeetingParticipant"
                ],
                "parameters": [
                    {
                        "name": "period",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "1month",
                                "3months",
                                "6months",
                                "1year"
                            ]
                        },
                        "description": "Reporting window."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Report object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "summary": {},
                                        "by_status": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_type": {},
                                        "monthly_trend": {},
                                        "attendance": {},
                                        "attendance_rate": {},
                                        "top_organizers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Error"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mobile/device-token": {
            "delete": {
                "operationId": "delete_api_mobile_device_token",
                "tags": [
                    "Mobile Device Tokens"
                ],
                "summary": "Unregister a push device token",
                "description": "Removes the push-notification device token of the current user so the device stops receiving notifications (call on logout).",
                "x-section": "Mobile App",
                "x-surface": "mobile",
                "x-controller": "Api\\Mobile\\MobileDeviceTokenController@destroy",
                "x-source": "app/Http/Controllers/Api/Mobile/MobileDeviceTokenController.php#L43-L54",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "MobileDeviceToken"
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 255,
                            "x-laravel-rules": [
                                "required",
                                "string",
                                "max:255"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "FCM token."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"status\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_mobile_device_token",
                "tags": [
                    "Mobile Device Tokens"
                ],
                "summary": "Register a push device token",
                "description": "Upsert by token; a token moving between accounts is re-assigned.",
                "x-section": "Mobile App",
                "x-surface": "mobile",
                "x-controller": "Api\\Mobile\\MobileDeviceTokenController@store",
                "x-source": "app/Http/Controllers/Api/Mobile/MobileDeviceTokenController.php#L18-L41",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "MobileDeviceToken"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "app_version": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "App version."
                                    },
                                    "device_name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Device label."
                                    },
                                    "platform": {
                                        "type": "string",
                                        "enum": [
                                            "android",
                                            "ios"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "in:android,ios"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`android` or `ios`."
                                    },
                                    "token": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "FCM token."
                                    }
                                },
                                "required": [
                                    "token"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"status\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mobile/device-token/test": {
            "post": {
                "operationId": "post_api_mobile_device_token_test",
                "tags": [
                    "Mobile Device Tokens"
                ],
                "summary": "Send a test push",
                "description": "Sends a test notification to all of the caller's devices; `enabled: false` when Firebase is not configured.",
                "x-section": "Mobile App",
                "x-surface": "mobile",
                "x-controller": "Api\\Mobile\\MobileDeviceTokenController@test",
                "x-source": "app/Http/Controllers/Api/Mobile/MobileDeviceTokenController.php#L56-L78",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "MobileDeviceToken"
                ],
                "responses": {
                    "200": {
                        "description": "`status`, `enabled`, `devices`, optional `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "enabled": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "devices": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Push is not configured on this server (missing Firebase service-account file)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mobile/login": {
            "post": {
                "operationId": "post_api_mobile_login",
                "tags": [
                    "Mobile Authentication"
                ],
                "summary": "Mobile login",
                "description": "Rate-limited (10/min). Returns a Passport bearer token plus the user and its permission names. Refused for inactive users or when the mobile app is disabled.",
                "x-section": "Mobile App",
                "x-surface": "mobile",
                "x-public": true,
                "x-controller": "Api\\Mobile\\MobileAuthController@login",
                "x-source": "app/Http/Controllers/Api/Mobile/MobileAuthController.php#L80-L129",
                "x-middleware": [
                    "api",
                    "throttle:10,1"
                ],
                "x-rate-limit": {
                    "requests": 10,
                    "per_minutes": 1
                },
                "x-models": [
                    "User",
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "device_name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Device label shown in the sessions list."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "password": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Password."
                                    }
                                },
                                "required": [
                                    "email",
                                    "password"
                                ]
                            },
                            "example": {
                                "email": "admin@example.com",
                                "password": "secret",
                                "device_name": "Pixel 8"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`status`, `token_type`, `access_token`, `user`, `permissions[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "token_type": {
                                            "type": "string",
                                            "example": "Bearer"
                                        },
                                        "access_token": {
                                            "type": "string"
                                        },
                                        "user": {},
                                        "permissions": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Incorrect login.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Incorrect Login"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "App disabled.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "AppDisabled"
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/api/mobile/logout": {
            "post": {
                "operationId": "post_api_mobile_logout",
                "tags": [
                    "Mobile Authentication"
                ],
                "summary": "Mobile logout",
                "description": "Revokes the current token and, when `device_token` is sent, forgets that push registration.",
                "x-section": "Mobile App",
                "x-surface": "mobile",
                "x-controller": "Api\\Mobile\\MobileAuthController@logout",
                "x-source": "app/Http/Controllers/Api/Mobile/MobileAuthController.php#L146-L172",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "UserLoginSession",
                    "MobileDeviceToken"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "device_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "FCM token of this device."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"status\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mobile/me": {
            "get": {
                "operationId": "get_api_mobile_me",
                "tags": [
                    "Mobile Authentication"
                ],
                "summary": "Current mobile user",
                "description": "The authenticated mobile user with role, permission names, assigned warehouses and the mobile settings relevant to the app (modules, offline mode, price edit).",
                "x-section": "Mobile App",
                "x-surface": "mobile",
                "x-controller": "Api\\Mobile\\MobileAuthController@me",
                "x-source": "app/Http/Controllers/Api/Mobile/MobileAuthController.php#L133-L142",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`user` and `permissions[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "user": {},
                                        "permissions": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mobile/ping": {
            "get": {
                "operationId": "get_api_mobile_ping",
                "tags": [
                    "Mobile Authentication"
                ],
                "summary": "Server handshake",
                "description": "Public. Validates a server URL typed into the app and negotiates versions: `api_version`, `min_app_version`, branding, currency, `mobile_enabled`, enabled `features` / `modules`.",
                "x-section": "Mobile App",
                "x-surface": "mobile",
                "x-public": true,
                "x-controller": "Api\\Mobile\\MobileAuthController@ping",
                "x-source": "app/Http/Controllers/Api/Mobile/MobileAuthController.php#L32-L76",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "Handshake object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "server": {
                                            "type": "string",
                                            "example": "stocky"
                                        },
                                        "api_version": {
                                            "type": "integer"
                                        },
                                        "min_app_version": {},
                                        "app_name": {},
                                        "logo": {},
                                        "default_language": {},
                                        "currency": {
                                            "type": "object",
                                            "properties": {
                                                "code": {},
                                                "symbol": {}
                                            }
                                        },
                                        "mobile_enabled": {},
                                        "maintenance_message": {},
                                        "branding": {
                                            "type": "object",
                                            "properties": {
                                                "primary_color": {},
                                                "theme_mode": {}
                                            }
                                        },
                                        "features": {
                                            "type": "object",
                                            "properties": {
                                                "offline": {
                                                    "type": "boolean"
                                                },
                                                "scanner": {
                                                    "type": "boolean"
                                                },
                                                "price_edit": {
                                                    "type": "boolean"
                                                }
                                            }
                                        },
                                        "modules": {},
                                        "support": {
                                            "type": "object",
                                            "properties": {
                                                "phone": {},
                                                "email": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/module_flags": {
            "delete": {
                "operationId": "delete_api_module_flags",
                "tags": [
                    "System Settings"
                ],
                "summary": "Reset business module flags",
                "description": "Removes the custom map so every module is visible again.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@resetModuleFlags",
                "x-source": "app/Http/Controllers/SettingsController.php#L1126-L1138",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "business_modules",
                        "slug": "business_modules | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_module_flags",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get business module flags",
                "description": "Returns the map of business-module keys to enabled booleans (e.g. `{\"hr\": true, \"projects\": false}`) or `null` when nothing has been customised (all modules visible). Any authenticated user may read it; the frontend uses it to hide menus.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@getModuleFlags",
                "x-source": "app/Http/Controllers/SettingsController.php#L1093-L1099",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{module_flags: object|null}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "module_flags": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_module_flags",
                "tags": [
                    "System Settings"
                ],
                "summary": "Save business module flags",
                "description": "Replaces the module-flag map. Only string keys are kept and every value is coerced to boolean, so a malformed payload cannot be stored. Requires `business_modules` or `setting_system`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@updateModuleFlags",
                "x-source": "app/Http/Controllers/SettingsController.php#L1101-L1124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "business_modules",
                        "slug": "business_modules | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "flags": {
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Object of module key → boolean.",
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "flags"
                                ]
                            },
                            "example": {
                                "flags": {
                                    "hr": true,
                                    "projects": true,
                                    "fleet": false,
                                    "hospital": false
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, module_flags}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "module_flags": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/boms": {
            "get": {
                "operationId": "get_api_mrp_boms",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "List bills of materials",
                "description": "Sortable `id, code, name, status, product_name`; `search` matches code, name or product.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@index",
                "x-source": "app/Http/Controllers/MrpBomController.php#L168-L230",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MrpBom"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`draft`, `active`, `archived`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`boms[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "boms": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_mrp_boms",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Create a BOM",
                "description": "Creates a bill of materials for a finished product: output quantity/unit, components (product, variant, quantity, scrap %), operations (work centre, minutes) and overhead. Only one BOM per product can be the default.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@store",
                "x-source": "app/Http/Controllers/MrpBomController.php#L325-L375",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpBom"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "x-unique": "mrp_boms,code",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:60",
                                            "unique:mrp_boms,code"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unique code."
                                    },
                                    "is_default": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default BOM for the product."
                                    },
                                    "lines": {
                                        "type": "array",
                                        "items": {},
                                        "description": "`[{product_id, product_variant_id?, qty, unit_id?, scrap_pct?, is_optional?, notes?}]`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "operations": {
                                        "type": "array",
                                        "items": {},
                                        "description": "`[{sequence, name, work_center_id, setup_minutes, run_minutes_per_unit, requires_qc?, instructions?}]`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "output_qty": {
                                        "type": "number",
                                        "minimum": 0.0001,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.0001"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Units produced per run."
                                    },
                                    "overhead_cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Fixed overhead per run."
                                    },
                                    "product_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "products,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Finished product."
                                    },
                                    "product_variant_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Variant."
                                    },
                                    "scrap_pct": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 99,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "max:99"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Expected scrap %."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "active",
                                            "archived"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:draft,active,archived"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "unit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Unit."
                                    },
                                    "version": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Version label.",
                                        "type": "string"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse (optional)."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name",
                                    "output_qty",
                                    "product_id"
                                ]
                            },
                            "example": {
                                "code": "BOM-CHAIR",
                                "name": "Wooden chair",
                                "product_id": 501,
                                "output_qty": 1,
                                "status": "active",
                                "scrap_pct": 2,
                                "lines": [
                                    {
                                        "product_id": 120,
                                        "qty": 4,
                                        "scrap_pct": 5
                                    },
                                    {
                                        "product_id": 121,
                                        "qty": 1
                                    }
                                ],
                                "operations": [
                                    {
                                        "sequence": 1,
                                        "name": "Cut",
                                        "work_center_id": 1,
                                        "setup_minutes": 15,
                                        "run_minutes_per_unit": 10
                                    },
                                    {
                                        "sequence": 2,
                                        "name": "Assemble",
                                        "work_center_id": 2,
                                        "setup_minutes": 5,
                                        "run_minutes_per_unit": 25,
                                        "requires_qc": true
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/boms/{id}": {
            "delete": {
                "operationId": "delete_api_mrp_boms_id",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Delete a BOM",
                "description": "Deletes a BOM. BOMs used by open production orders cannot be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@destroy",
                "x-source": "app/Http/Controllers/MrpBomController.php#L432-L454",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpBom",
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "BOM id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Used by open production orders.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "That bill of materials is used by open production orders. Archive it instead."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_mrp_boms_id",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Get a BOM",
                "description": "Header, `lines[]` (with unit cost and qty incl. scrap), `operations[]` (with labour / overhead cost) and the `costing` summary.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@show",
                "x-source": "app/Http/Controllers/MrpBomController.php#L232-L323",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpBom",
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "BOM id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`bom`, `lines[]`, `operations[]`, `costing`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "product_id": {},
                                        "product_name": {},
                                        "product_code": {},
                                        "qty": {
                                            "type": "number"
                                        },
                                        "qty_with_scrap": {},
                                        "unit_id": {},
                                        "scrap_pct": {
                                            "type": "number"
                                        },
                                        "is_optional": {
                                            "type": "boolean"
                                        },
                                        "unit_cost": {
                                            "type": "number"
                                        },
                                        "line_cost": {
                                            "type": "number"
                                        },
                                        "notes": {},
                                        "sort_order": {
                                            "type": "integer"
                                        },
                                        "sequence": {
                                            "type": "integer"
                                        },
                                        "name": {},
                                        "work_center_id": {},
                                        "work_center_name": {},
                                        "setup_minutes": {
                                            "type": "number"
                                        },
                                        "run_minutes_per_unit": {
                                            "type": "number"
                                        },
                                        "minutes_per_run": {
                                            "type": "number"
                                        },
                                        "labour_cost": {},
                                        "overhead_cost": {},
                                        "requires_qc": {
                                            "type": "boolean"
                                        },
                                        "instructions": {},
                                        "bom": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "code": {},
                                                "name": {},
                                                "product_id": {},
                                                "product_name": {},
                                                "product_code": {},
                                                "output_qty": {
                                                    "type": "number"
                                                },
                                                "unit_id": {},
                                                "warehouse_id": {},
                                                "version": {
                                                    "type": "integer"
                                                },
                                                "status": {},
                                                "is_default": {
                                                    "type": "boolean"
                                                },
                                                "scrap_pct": {
                                                    "type": "number"
                                                },
                                                "overhead_cost": {
                                                    "type": "number"
                                                },
                                                "notes": {},
                                                "requires_qc": {}
                                            }
                                        },
                                        "lines": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "operations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "costing": {
                                            "type": "object",
                                            "properties": {
                                                "material": {},
                                                "labour": {},
                                                "overhead": {},
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "per_unit": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_mrp_boms_id",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Update a BOM",
                "description": "Lines and operations are replaced when sent.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@update",
                "x-source": "app/Http/Controllers/MrpBomController.php#L377-L430",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpBom"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "BOM id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'required|string|max:60|unique:mrp_boms,code,' . $id"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'required|string|max:60|unique:mrp_boms,code,' . $id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unique code."
                                    },
                                    "is_default": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default BOM for the product."
                                    },
                                    "lines": {
                                        "type": "array",
                                        "items": {},
                                        "description": "Components (full replacement).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "operations": {
                                        "type": "array",
                                        "items": {},
                                        "description": "Routing (full replacement).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "output_qty": {
                                        "type": "number",
                                        "minimum": 0.0001,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.0001"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Units produced per run."
                                    },
                                    "overhead_cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Fixed overhead per run."
                                    },
                                    "product_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "products,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Finished product."
                                    },
                                    "product_variant_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Variant."
                                    },
                                    "scrap_pct": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 99,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "max:99"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Expected scrap %."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "active",
                                            "archived"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:draft,active,archived"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "unit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Unit."
                                    },
                                    "version": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Version label.",
                                        "type": "string"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse (optional)."
                                    }
                                },
                                "required": [
                                    "name",
                                    "output_qty",
                                    "product_id"
                                ]
                            },
                            "example": {
                                "code": "BOM-CHAIR",
                                "name": "Wooden chair",
                                "product_id": 501,
                                "output_qty": 1,
                                "status": "active",
                                "scrap_pct": 2,
                                "lines": [
                                    {
                                        "product_id": 120,
                                        "qty": 4,
                                        "scrap_pct": 5
                                    },
                                    {
                                        "product_id": 121,
                                        "qty": 1
                                    }
                                ],
                                "operations": [
                                    {
                                        "sequence": 1,
                                        "name": "Cut",
                                        "work_center_id": 1,
                                        "setup_minutes": 15,
                                        "run_minutes_per_unit": 10
                                    },
                                    {
                                        "sequence": 2,
                                        "name": "Assemble",
                                        "work_center_id": 2,
                                        "setup_minutes": 5,
                                        "run_minutes_per_unit": 25,
                                        "requires_qc": true
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/boms/{id}/duplicate": {
            "post": {
                "operationId": "post_api_mrp_boms_id_duplicate",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Duplicate as next version",
                "description": "Copy a BOM as the next version — the safe way to change a live recipe.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@duplicate",
                "x-source": "app/Http/Controllers/MrpBomController.php#L457-L506",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpBom",
                    "MrpBomLine",
                    "MrpBomOperation"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "BOM id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and new `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/boms/{id}/explode": {
            "get": {
                "operationId": "get_api_mrp_boms_id_explode",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Multi-level explosion",
                "description": "Flattened requirement tree for `qty` units (default the BOM output), with cost per level and loop detection.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@explode",
                "x-source": "app/Http/Controllers/MrpBomController.php#L509-L541",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpBom",
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "BOM id."
                    },
                    {
                        "name": "qty",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "number"
                        },
                        "description": "Quantity to build."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `loops`, `depth`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "level": {},
                                        "product_id": {},
                                        "product_name": {},
                                        "product_code": {},
                                        "qty": {
                                            "type": "integer"
                                        },
                                        "unit_cost": {
                                            "type": "number"
                                        },
                                        "total_cost": {
                                            "type": "number"
                                        },
                                        "is_optional": {},
                                        "has_bom": {
                                            "type": "boolean"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "loops": {},
                                        "depth": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/dashboard": {
            "get": {
                "operationId": "get_api_mrp_dashboard",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Manufacturing dashboard",
                "description": "Manufacturing KPIs: open production orders by status, work-order load per work centre, material shortages, quality pass rate and recent completions.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@dashboard",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L234-L379",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder",
                    "MrpQualityCheck",
                    "MrpWorkOrder",
                    "MrpPlanningRun",
                    "MrpWorkCenter",
                    "MrpBom",
                    "MrpPlanningSuggestion"
                ],
                "responses": {
                    "200": {
                        "description": "Order counts by status, late / blocked orders, produced and scrapped this month, cost, QC pass rate, output trend, load by work centre, latest planning run and pending suggestions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "orders_total": {
                                            "type": "integer"
                                        },
                                        "orders_draft": {
                                            "type": "integer"
                                        },
                                        "orders_planned": {
                                            "type": "integer"
                                        },
                                        "orders_released": {
                                            "type": "integer"
                                        },
                                        "orders_in_progress": {
                                            "type": "integer"
                                        },
                                        "orders_completed": {
                                            "type": "integer"
                                        },
                                        "orders_open": {},
                                        "orders_late": {},
                                        "open_work_orders": {},
                                        "produced_month": {
                                            "type": "number"
                                        },
                                        "scrapped_month": {
                                            "type": "number"
                                        },
                                        "scrap_rate_month": {
                                            "type": "number"
                                        },
                                        "cost_month": {
                                            "type": "number"
                                        },
                                        "qc_inspected_30d": {
                                            "type": "number"
                                        },
                                        "qc_rejected_30d": {
                                            "type": "number"
                                        },
                                        "qc_pass_rate_30d": {
                                            "type": "number"
                                        },
                                        "work_centers": {
                                            "type": "integer"
                                        },
                                        "active_boms": {
                                            "type": "integer"
                                        },
                                        "output_trend": {},
                                        "load_by_work_center": {},
                                        "blocked_orders": {},
                                        "recent_orders": {},
                                        "latest_run": {},
                                        "pending_suggestions": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/meta": {
            "get": {
                "operationId": "get_api_mrp_meta",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Manufacturing form lookups",
                "description": "Select options every manufacturing page shares.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@meta",
                "x-source": "app/Http/Controllers/MrpBomController.php#L640-L683",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Unit",
                    "MrpWorkCenter",
                    "MrpBom"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]`, `units[]`, `work_centers[]`, `boms[]`, `employees[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "units": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "work_centers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "boms": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/planning/run": {
            "post": {
                "operationId": "post_api_mrp_planning_run",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Run MRP planning",
                "description": "Explodes demand over the horizon against stock (optionally including safety stock) and stores suggestions. Long-running.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@run",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L37-L67",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_planning",
                        "policy": "MrpPlanningRunPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "horizon_end": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:horizon_start"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:horizon_start"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Horizon end."
                                    },
                                    "horizon_start": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Horizon start."
                                    },
                                    "include_safety_stock": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treat stock alert levels as demand.",
                                        "type": "boolean"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse whose stock is planned."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `run`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "run": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/planning/runs": {
            "get": {
                "operationId": "get_api_mrp_planning_runs",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "List planning runs",
                "description": "History of MRP planning runs with date, horizon, number of suggestions and the user who ran them.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@runs",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L69-L90",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_planning",
                        "policy": "MrpPlanningRunPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MrpPlanningRun"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`runs[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "runs": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/planning/suggestions": {
            "get": {
                "operationId": "get_api_mrp_planning_suggestions",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "List suggestions",
                "description": "Paginated suggestions from the last planning run: product, suggested quantity, reason (below reorder point / demand), suggested action (purchase or produce) and status.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@suggestions",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L111-L169",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_planning",
                        "policy": "MrpPlanningRunPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MrpPlanningSuggestion",
                    "MrpPlanningRun"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "action",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`make` or `buy`."
                    },
                    {
                        "name": "planning_run_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Run."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `accepted`, `dismissed`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`suggestions[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "suggestions": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/planning/suggestions/accept-all": {
            "post": {
                "operationId": "post_api_mrp_planning_suggestions_accept_all",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Accept all pending make suggestions of a run",
                "description": "Accept every pending \"make\" suggestion on a run, deepest level first.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@acceptAll",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L191-L216",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpPlanningSuggestion"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "planning_run_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "mrp_planning_runs,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:mrp_planning_runs,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Run id."
                                    }
                                },
                                "required": [
                                    "planning_run_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `created`, `failed[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "created": {},
                                        "failed": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/planning/suggestions/{id}/accept": {
            "post": {
                "operationId": "post_api_mrp_planning_suggestions_id_accept",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Accept a suggestion",
                "description": "Creates a draft production order for a *make* suggestion.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@acceptSuggestion",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L172-L188",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpPlanningSuggestion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Suggestion id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success`, `order_id`, `reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "order_id": {},
                                        "reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Cannot accept (e.g. no active BOM).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/planning/suggestions/{id}/dismiss": {
            "post": {
                "operationId": "post_api_mrp_planning_suggestions_id_dismiss",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Dismiss a suggestion",
                "description": "Marks a suggestion as dismissed so it no longer appears as pending.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@dismissSuggestion",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L218-L230",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_planning",
                        "policy": "MrpPlanningRunPolicy"
                    }
                ],
                "x-models": [
                    "MrpPlanningSuggestion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Suggestion id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "That suggestion has already been dealt with."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/production-orders": {
            "get": {
                "operationId": "get_api_mrp_production_orders",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "List production orders",
                "description": "Sortable `id, reference, status, priority, planned_start, qty_planned`; rows include costs, yield, scrap and progress percentages and `is_late`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@index",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L37-L158",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Planned start from."
                    },
                    {
                        "name": "priority",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Priority."
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Planned start to."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`orders[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "reference": {},
                                        "product_id": {},
                                        "product_name": {},
                                        "product_code": {},
                                        "warehouse_id": {},
                                        "warehouse_name": {},
                                        "qty_planned": {
                                            "type": "number"
                                        },
                                        "qty_produced": {
                                            "type": "number"
                                        },
                                        "qty_scrapped": {
                                            "type": "number"
                                        },
                                        "status": {},
                                        "priority": {},
                                        "planned_start": {
                                            "type": "string"
                                        },
                                        "planned_end": {
                                            "type": "string"
                                        },
                                        "material_cost": {
                                            "type": "number"
                                        },
                                        "labour_cost": {
                                            "type": "number"
                                        },
                                        "overhead_cost": {
                                            "type": "number"
                                        },
                                        "total_cost": {
                                            "type": "number"
                                        },
                                        "unit_cost": {
                                            "type": "number"
                                        },
                                        "planned_cost": {
                                            "type": "number"
                                        },
                                        "cost_variance": {},
                                        "cost_variance_pct": {},
                                        "yield_pct": {},
                                        "scrap_pct": {},
                                        "progress_pct": {},
                                        "materials_issued": {
                                            "type": "boolean"
                                        },
                                        "qc_required": {
                                            "type": "boolean"
                                        },
                                        "is_late": {},
                                        "orders": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "cost": {
                                                    "type": "number"
                                                },
                                                "planned": {
                                                    "type": "number"
                                                },
                                                "produced": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_mrp_production_orders",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Create a production order",
                "description": "Copies the BOM (default one when omitted) into materials and work orders scaled to `qty_planned`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@store",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L283-L338",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpBom",
                    "MrpProductionOrder"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "bom_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "mrp_boms,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:mrp_boms,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "BOM (default: product's default BOM)."
                                    },
                                    "fg_warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse receiving finished goods (default same)."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "planned_end": {
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:planned_start"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:planned_start"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Planned end.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "planned_start": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Planned start.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "priority": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "low",
                                            "normal",
                                            "high",
                                            "urgent"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:low,normal,high,urgent"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Priority."
                                    },
                                    "product_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "products,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product to make."
                                    },
                                    "product_variant_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Variant."
                                    },
                                    "qty_planned": {
                                        "type": "number",
                                        "minimum": 0.0001,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.0001"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Quantity."
                                    },
                                    "sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale that triggered the order."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Initial status (`draft` or `planned`)."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse consuming materials."
                                    }
                                },
                                "required": [
                                    "product_id",
                                    "qty_planned",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/production-orders/{id}": {
            "delete": {
                "operationId": "delete_api_mrp_production_orders_id",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Delete a production order",
                "description": "Deletes a production order. Only `draft` or `cancelled` orders can be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@destroy",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L397-L413",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Materials issued — cancel instead.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Materials have been issued against this order. Cancel it instead so the stock is returned."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_mrp_production_orders_id",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Get a production order",
                "description": "Order with `materials[]` (required / issued / consumed / on hand / shortfall), `work_orders[]`, `quality_checks[]` and current `shortages`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@show",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L160-L281",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder",
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`order`, `materials[]`, `work_orders[]`, `quality_checks[]`, `shortages`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "product_id": {},
                                        "product_name": {},
                                        "product_code": {},
                                        "qty_required": {
                                            "type": "number"
                                        },
                                        "qty_issued": {
                                            "type": "number"
                                        },
                                        "qty_returned": {
                                            "type": "number"
                                        },
                                        "qty_consumed": {},
                                        "shortfall": {},
                                        "on_hand": {
                                            "type": "number"
                                        },
                                        "unit_cost": {
                                            "type": "number"
                                        },
                                        "total_cost": {
                                            "type": "number"
                                        },
                                        "is_optional": {
                                            "type": "boolean"
                                        },
                                        "order": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "reference": {},
                                                "bom_id": {},
                                                "bom_name": {},
                                                "product_id": {},
                                                "product_name": {},
                                                "product_code": {},
                                                "warehouse_id": {},
                                                "warehouse_name": {},
                                                "fg_warehouse_id": {},
                                                "qty_planned": {
                                                    "type": "number"
                                                },
                                                "qty_produced": {
                                                    "type": "number"
                                                },
                                                "qty_scrapped": {
                                                    "type": "number"
                                                },
                                                "status": {},
                                                "priority": {},
                                                "planned_start": {
                                                    "type": "string"
                                                },
                                                "planned_end": {
                                                    "type": "string"
                                                },
                                                "actual_start": {
                                                    "type": "string"
                                                },
                                                "actual_end": {
                                                    "type": "string"
                                                },
                                                "material_cost": {
                                                    "type": "number"
                                                },
                                                "labour_cost": {
                                                    "type": "number"
                                                },
                                                "overhead_cost": {
                                                    "type": "number"
                                                },
                                                "total_cost": {
                                                    "type": "number"
                                                },
                                                "unit_cost": {
                                                    "type": "number"
                                                },
                                                "planned_cost": {
                                                    "type": "number"
                                                },
                                                "cost_variance": {},
                                                "cost_variance_pct": {},
                                                "yield_pct": {},
                                                "scrap_pct": {},
                                                "progress_pct": {},
                                                "planned_minutes": {},
                                                "actual_minutes": {},
                                                "materials_issued": {
                                                    "type": "boolean"
                                                },
                                                "qc_required": {
                                                    "type": "boolean"
                                                },
                                                "journal_entry_id": {},
                                                "notes": {}
                                            }
                                        },
                                        "materials": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "work_orders": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "quality_checks": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "shortages": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_mrp_production_orders_id",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Update a production order",
                "description": "Finished orders cannot be edited.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@update",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L340-L395",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "fg_warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse receiving finished goods (default same)."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "planned_end": {
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:planned_start"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:planned_start"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Planned end.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "planned_start": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Planned start.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "priority": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "low",
                                            "normal",
                                            "high",
                                            "urgent"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:low,normal,high,urgent"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Priority."
                                    },
                                    "qty_planned": {
                                        "type": "number",
                                        "minimum": 0.0001,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.0001"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Quantity."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse consuming materials."
                                    }
                                },
                                "required": [
                                    "qty_planned"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/production-orders/{id}/cancel": {
            "post": {
                "operationId": "post_api_mrp_production_orders_id_cancel",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Cancel the order",
                "description": "Returns issued materials to stock.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@cancel",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L520-L537",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/production-orders/{id}/complete": {
            "post": {
                "operationId": "post_api_mrp_production_orders_id_complete",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Complete the order",
                "description": "Books `qty_produced` into the finished-goods warehouse, records scrap, returns unused materials and computes actual cost and variance. Refused when a required final QC is missing unless `skip_qc`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@complete",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L477-L518",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "allow_overproduction": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow qty above planned."
                                    },
                                    "qty_produced": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Good units."
                                    },
                                    "qty_scrapped": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Scrapped units."
                                    },
                                    "skip_qc": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Skip the final quality check requirement.",
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "qty_produced"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `unit_cost`, `total_cost`, `cost_variance`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "unit_cost": {
                                            "type": "number"
                                        },
                                        "total_cost": {
                                            "type": "number"
                                        },
                                        "cost_variance": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/production-orders/{id}/release": {
            "post": {
                "operationId": "post_api_mrp_production_orders_id_release",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Release to production",
                "description": "Issues materials from stock and moves the order to `released`. Without `allow_shortage` the call fails and returns the `shortages`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@release",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L417-L442",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "allow_shortage": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Release even if some components are short."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "`message` and `shortages[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {},
                                        "shortages": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/products": {
            "get": {
                "operationId": "get_api_mrp_products",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Product search for component pickers",
                "description": "Product search for the component pickers — never the whole catalogue.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@products",
                "x-source": "app/Http/Controllers/MrpBomController.php#L686-L714",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name or code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`products[] {id, name, code, cost, price, unit_id, stock_alert}` (max 50).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/quality-checks": {
            "get": {
                "operationId": "get_api_mrp_quality_checks",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "List quality checks",
                "description": "Paginated quality checks with production/work order, inspector, result (pass/fail), quantities and notes.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@qualityChecks",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L655-L726",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_quality",
                        "policy": "MrpQualityCheckPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MrpQualityCheck"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "production_order_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Order."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`passed` / `failed`."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`in_process` / `final`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`checks[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "checks": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "inspected": {
                                                    "type": "number"
                                                },
                                                "rejected": {
                                                    "type": "number"
                                                },
                                                "pass_rate": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_mrp_quality_checks",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Record a quality check",
                "description": "Status is `failed` when anything is rejected or a line fails.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@storeQualityCheck",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L728-L800",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_quality",
                        "policy": "MrpQualityCheckPolicy"
                    }
                ],
                "x-models": [
                    "MrpQualityCheck",
                    "MrpQualityCheckLine",
                    "MrpProductionOrder"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "lines": {
                                        "type": "array",
                                        "items": {},
                                        "description": "`[{parameter, expected, actual, result: pass|fail, notes?}]`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "production_order_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "mrp_production_orders,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:mrp_production_orders,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Order."
                                    },
                                    "qty_inspected": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Units inspected."
                                    },
                                    "qty_rejected": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Units rejected."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "in_process",
                                            "final"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:in_process,final"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`in_process` or `final`."
                                    },
                                    "work_order_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Related work order."
                                    }
                                },
                                "required": [
                                    "production_order_id",
                                    "qty_inspected",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/quality-checks/{id}": {
            "delete": {
                "operationId": "delete_api_mrp_quality_checks_id",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Delete a quality check",
                "description": "Deletes a quality check record.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@destroyQualityCheck",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L802-L810",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "mrp_quality",
                        "policy": "MrpQualityCheckPolicy"
                    }
                ],
                "x-models": [
                    "MrpQualityCheck"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Check id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/reports/cost": {
            "get": {
                "operationId": "get_api_mrp_reports_cost",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Cost & variance report",
                "description": "One row per completed order: planned vs actual material / labour / overhead cost, unit cost and variance.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@costReport",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L384-L434",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpProductionOrder"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Completed from."
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Completed to."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "orders": {
                                                    "type": "integer"
                                                },
                                                "produced": {
                                                    "type": "number"
                                                },
                                                "scrapped": {
                                                    "type": "number"
                                                },
                                                "material": {
                                                    "type": "number"
                                                },
                                                "labour": {
                                                    "type": "number"
                                                },
                                                "overhead": {
                                                    "type": "number"
                                                },
                                                "total": {
                                                    "type": "number"
                                                },
                                                "variance": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/reports/efficiency": {
            "get": {
                "operationId": "get_api_mrp_reports_efficiency",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Work-centre efficiency report",
                "description": "Work-centre efficiency: booked time against allowed time.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@efficiencyReport",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L437-L493",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpWorkOrder"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (planned vs actual hours, efficiency %, reject rate) and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "code": {},
                                        "operations": {
                                            "type": "integer"
                                        },
                                        "planned_hours": {
                                            "type": "number"
                                        },
                                        "actual_hours": {
                                            "type": "number"
                                        },
                                        "efficiency_pct": {
                                            "type": "number"
                                        },
                                        "labour_cost": {
                                            "type": "number"
                                        },
                                        "overhead_cost": {
                                            "type": "number"
                                        },
                                        "qty_completed": {
                                            "type": "number"
                                        },
                                        "qty_rejected": {
                                            "type": "number"
                                        },
                                        "reject_rate": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "operations": {
                                                    "type": "integer"
                                                },
                                                "planned_hours": {
                                                    "type": "number"
                                                },
                                                "actual_hours": {
                                                    "type": "number"
                                                },
                                                "labour_cost": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/reports/material": {
            "get": {
                "operationId": "get_api_mrp_reports_material",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Material consumption report",
                "description": "Material consumption: planned against actual, per component.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@materialReport",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L496-L545",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (required vs consumed, variance, cost) and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "code": {},
                                        "orders": {
                                            "type": "integer"
                                        },
                                        "required": {
                                            "type": "number"
                                        },
                                        "consumed": {
                                            "type": "number"
                                        },
                                        "variance": {
                                            "type": "number"
                                        },
                                        "variance_pct": {
                                            "type": "number"
                                        },
                                        "cost": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "required": {
                                                    "type": "number"
                                                },
                                                "consumed": {
                                                    "type": "number"
                                                },
                                                "cost": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/reports/quality": {
            "get": {
                "operationId": "get_api_mrp_reports_quality",
                "tags": [
                    "MRP: Planning"
                ],
                "summary": "Quality report",
                "description": "Quality: pass rates by product.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpPlanningController@qualityReport",
                "x-source": "app/Http/Controllers/MrpPlanningController.php#L548-L597",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_quality",
                        "policy": "MrpQualityCheckPolicy"
                    }
                ],
                "x-models": [
                    "MrpQualityCheck"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (checks, inspected, passed, rejected, pass rate per product) and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "code": {},
                                        "checks": {
                                            "type": "integer"
                                        },
                                        "failed_checks": {
                                            "type": "integer"
                                        },
                                        "inspected": {
                                            "type": "number"
                                        },
                                        "passed": {
                                            "type": "number"
                                        },
                                        "rejected": {
                                            "type": "number"
                                        },
                                        "pass_rate": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "checks": {
                                                    "type": "integer"
                                                },
                                                "inspected": {
                                                    "type": "number"
                                                },
                                                "rejected": {
                                                    "type": "number"
                                                },
                                                "pass_rate": {
                                                    "type": "number"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/work-centers": {
            "get": {
                "operationId": "get_api_mrp_work_centers",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "List work centres",
                "description": "Work centres with capacity per hour, hourly cost, efficiency and active flag.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@workCenters",
                "x-source": "app/Http/Controllers/MrpBomController.php#L30-L77",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MrpWorkCenter"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`work_centers[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "work_centers": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_mrp_work_centers",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Create a work centre",
                "description": "Creates a work centre (machine or station) used in BOM operations and work orders.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@storeWorkCenter",
                "x-source": "app/Http/Controllers/MrpBomController.php#L79-L102",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpWorkCenter"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "capacity_per_hour": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Units per hour.",
                                        "type": "number"
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "x-unique": "mrp_work_centers,code",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:60",
                                            "unique:mrp_work_centers,code"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unique code."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "efficiency_pct": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Efficiency 1–200 %."
                                    },
                                    "hourly_cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Labour cost per hour."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "overhead_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Overhead per hour."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse (optional = company-wide)."
                                    }
                                },
                                "required": [
                                    "code",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "code": {},
                                        "name": {},
                                        "warehouse_id": {},
                                        "capacity_per_hour": {
                                            "type": "number"
                                        },
                                        "hourly_cost": {
                                            "type": "number"
                                        },
                                        "overhead_rate": {
                                            "type": "number"
                                        },
                                        "efficiency_pct": {
                                            "type": "integer"
                                        },
                                        "description": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/work-centers/{id}": {
            "delete": {
                "operationId": "delete_api_mrp_work_centers_id",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Delete a work centre",
                "description": "Deletes a work centre not referenced by open work orders.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@destroyWorkCenter",
                "x-source": "app/Http/Controllers/MrpBomController.php#L127-L149",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpWorkCenter"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Work centre id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Open work orders exist.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "That work centre has open work orders. Finish or reassign them first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_mrp_work_centers_id",
                "tags": [
                    "MRP: Bills of Materials"
                ],
                "summary": "Update a work centre",
                "description": "Updates a work centre with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpBomController@updateWorkCenter",
                "x-source": "app/Http/Controllers/MrpBomController.php#L104-L125",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_boms",
                        "policy": "MrpBomPolicy"
                    }
                ],
                "x-models": [
                    "MrpWorkCenter"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Work centre id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "capacity_per_hour": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Units per hour.",
                                        "type": "number"
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'required|string|max:60|unique:mrp_work_centers,code,' . $id"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'required|string|max:60|unique:mrp_work_centers,code,' . $id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unique code."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "efficiency_pct": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Efficiency 1–200 %."
                                    },
                                    "hourly_cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Labour cost per hour."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "overhead_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Overhead per hour."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse (optional = company-wide)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "code": {},
                                        "name": {},
                                        "warehouse_id": {},
                                        "capacity_per_hour": {
                                            "type": "number"
                                        },
                                        "hourly_cost": {
                                            "type": "number"
                                        },
                                        "overhead_rate": {
                                            "type": "number"
                                        },
                                        "efficiency_pct": {
                                            "type": "integer"
                                        },
                                        "description": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/work-orders": {
            "get": {
                "operationId": "get_api_mrp_work_orders",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Shop-floor queue",
                "description": "Work orders joined with order reference, product, work centre and operator. By default only open ones.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@workOrders",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L542-L615",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "MrpWorkOrder"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "employee_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Operator."
                    },
                    {
                        "name": "include_all",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = include completed."
                    },
                    {
                        "name": "production_order_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Order."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `in_progress`, `completed`."
                    },
                    {
                        "name": "work_center_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Work centre."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`work_orders[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "work_orders": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/work-orders/{id}/finish": {
            "post": {
                "operationId": "post_api_mrp_work_orders_id_finish",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Finish a work order",
                "description": "Books actual minutes (labour + overhead cost) and completed / rejected quantities.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@finishWorkOrder",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L631-L651",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpWorkOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Work order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "actual_minutes": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Time spent."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Operator."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "qty_completed": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Units completed."
                                    },
                                    "qty_rejected": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Units rejected."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `labour_cost`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "labour_cost": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/mrp/work-orders/{id}/start": {
            "post": {
                "operationId": "post_api_mrp_work_orders_id_start",
                "tags": [
                    "MRP: Production"
                ],
                "summary": "Start a work order",
                "description": "Moves a work order to `in_progress` and stamps the actual start time.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "MrpProductionController@startWorkOrder",
                "x-source": "app/Http/Controllers/MrpProductionController.php#L617-L629",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "mrp_production",
                        "policy": "MrpProductionOrderPolicy"
                    }
                ],
                "x-models": [
                    "MrpWorkOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Work order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Operator."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Previous operation not finished / order not released.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/office_shift": {
            "get": {
                "operationId": "get_api_office_shift",
                "tags": [
                    "Office Shifts"
                ],
                "summary": "List office shifts",
                "description": "Paginated shifts with `company_id`, `company_name` and the 14 `<day>_in` / `<day>_out` times as `HH:MM` (AM/PM suffix stripped). `search` matches the shift name.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@index",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L16-L72",
                "x-route-name": "office_shift.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "OfficeShift"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`office_shifts[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "office_shifts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_office_shift",
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Create an office shift",
                "description": "Times are parsed with `DateTime` and stored as `H:iA`. Send `HH:MM` (24h) or leave a day empty/null for a day off.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@store",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L88-L132",
                "x-route-name": "office_shift.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-models": [
                    "OfficeShift"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "friday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Friday start."
                                    },
                                    "friday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Friday end."
                                    },
                                    "monday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Monday start `HH:MM`."
                                    },
                                    "monday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Monday end."
                                    },
                                    "name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Shift name."
                                    },
                                    "saturday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Saturday start."
                                    },
                                    "saturday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Saturday end."
                                    },
                                    "sunday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sunday start."
                                    },
                                    "sunday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sunday end."
                                    },
                                    "thursday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Thursday start."
                                    },
                                    "thursday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Thursday end."
                                    },
                                    "tuesday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tuesday start."
                                    },
                                    "tuesday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tuesday end."
                                    },
                                    "wednesday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wednesday start."
                                    },
                                    "wednesday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wednesday end."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Day shift",
                                "company_id": 1,
                                "monday_in": "09:00",
                                "monday_out": "17:00",
                                "tuesday_in": "09:00",
                                "tuesday_out": "17:00",
                                "wednesday_in": "09:00",
                                "wednesday_out": "17:00",
                                "thursday_in": "09:00",
                                "thursday_out": "17:00",
                                "friday_in": "09:00",
                                "friday_out": "17:00",
                                "saturday_in": null,
                                "saturday_out": null,
                                "sunday_in": null,
                                "sunday_out": null
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/office_shift/create": {
            "get": {
                "operationId": "get_api_office_shift_create",
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Create-form data for an office shift",
                "description": "Lookup data for the office-shift form (companies).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@create",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L74-L84",
                "x-route-name": "office_shift.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/office_shift/delete/by_selection": {
            "post": {
                "operationId": "post_api_office_shift_delete_by_selection",
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Delete selected office shifts",
                "description": "Bulk soft-delete of office shifts by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@delete_by_selection",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L301-L314",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-models": [
                    "OfficeShift"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shift ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/office_shift/{office_shift}": {
            "delete": {
                "operationId": "delete_api_office_shift_office_shift",
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Delete an office shift",
                "description": "Soft-deletes an office shift. Employees keep their `office_shift_id`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@destroy",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L284-L297",
                "x-route-name": "office_shift.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-models": [
                    "OfficeShift"
                ],
                "parameters": [
                    {
                        "name": "office_shift",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shift id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_office_shift_office_shift",
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Get an office shift (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@show",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L136-L140",
                "x-route-name": "office_shift.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "office_shift",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shift id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_office_shift_office_shift",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Update an office shift",
                "description": "Accepts either `HH:MM` (5 chars) or the stored `HH:MMAM` form for each time. Same fields as create.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@update",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L158-L280",
                "x-route-name": "office_shift.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-models": [
                    "OfficeShift"
                ],
                "parameters": [
                    {
                        "name": "office_shift",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shift id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "friday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Friday start."
                                    },
                                    "friday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Friday end."
                                    },
                                    "monday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Monday start `HH:MM`."
                                    },
                                    "monday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Monday end."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shift name."
                                    },
                                    "saturday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Saturday start."
                                    },
                                    "saturday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Saturday end."
                                    },
                                    "sunday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sunday start."
                                    },
                                    "sunday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sunday end."
                                    },
                                    "thursday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Thursday start."
                                    },
                                    "thursday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Thursday end."
                                    },
                                    "tuesday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tuesday start."
                                    },
                                    "tuesday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tuesday end."
                                    },
                                    "wednesday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wednesday start."
                                    },
                                    "wednesday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wednesday end."
                                    }
                                }
                            },
                            "example": {
                                "name": "Day shift",
                                "company_id": 1,
                                "monday_in": "09:00",
                                "monday_out": "17:00",
                                "tuesday_in": "09:00",
                                "tuesday_out": "17:00",
                                "wednesday_in": "09:00",
                                "wednesday_out": "17:00",
                                "thursday_in": "09:00",
                                "thursday_out": "17:00",
                                "friday_in": "09:00",
                                "friday_out": "17:00",
                                "saturday_in": null,
                                "saturday_out": null,
                                "sunday_in": null,
                                "sunday_out": null
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_office_shift_office_shift",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Update an office shift",
                "description": "Accepts either `HH:MM` (5 chars) or the stored `HH:MMAM` form for each time. Same fields as create.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@update",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L158-L280",
                "x-route-name": "office_shift.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-models": [
                    "OfficeShift"
                ],
                "parameters": [
                    {
                        "name": "office_shift",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shift id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "friday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Friday start."
                                    },
                                    "friday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Friday end."
                                    },
                                    "monday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Monday start `HH:MM`."
                                    },
                                    "monday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Monday end."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shift name."
                                    },
                                    "saturday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Saturday start."
                                    },
                                    "saturday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Saturday end."
                                    },
                                    "sunday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sunday start."
                                    },
                                    "sunday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sunday end."
                                    },
                                    "thursday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Thursday start."
                                    },
                                    "thursday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Thursday end."
                                    },
                                    "tuesday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tuesday start."
                                    },
                                    "tuesday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tuesday end."
                                    },
                                    "wednesday_in": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wednesday start."
                                    },
                                    "wednesday_out": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wednesday end."
                                    }
                                }
                            },
                            "example": {
                                "name": "Day shift",
                                "company_id": 1,
                                "monday_in": "09:00",
                                "monday_out": "17:00",
                                "tuesday_in": "09:00",
                                "tuesday_out": "17:00",
                                "wednesday_in": "09:00",
                                "wednesday_out": "17:00",
                                "thursday_in": "09:00",
                                "thursday_out": "17:00",
                                "friday_in": "09:00",
                                "friday_out": "17:00",
                                "saturday_in": null,
                                "saturday_out": null,
                                "sunday_in": null,
                                "sunday_out": null
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/office_shift/{office_shift}/edit": {
            "get": {
                "operationId": "get_api_office_shift_office_shift_edit",
                "tags": [
                    "Office Shifts"
                ],
                "summary": "Edit-form data for an office shift",
                "description": "The office shift with the lookups needed by the edit form.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\OfficeShiftController@edit",
                "x-source": "app/Http/Controllers/hrm/OfficeShiftController.php#L144-L154",
                "x-route-name": "office_shift.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "OfficeShiftPolicy"
                    }
                ],
                "x-models": [
                    "Company"
                ],
                "parameters": [
                    {
                        "name": "office_shift",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shift id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/one_click_update": {
            "post": {
                "operationId": "post_api_one_click_update",
                "tags": [
                    "System Update"
                ],
                "summary": "Run one-click update",
                "description": "Downloads the latest release from the update server, verifies the version, backs up the codebase and database, extracts the package, runs migrations and clears caches. Progress is written to `storage/app/update_progress.json` (read via `GET /api/update/progress`). A lock prevents concurrent runs. On failure the previous code and database are restored automatically. This request can take several minutes; the server disables the execution time limit.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "AutoUpdateController@oneClickUpdate",
                "x-source": "app/Http/Controllers/AutoUpdateController.php#L17-L281",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{message: \"Successfully Updated\", version}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Successfully Updated"
                                        },
                                        "version": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Version in metadata does not match the downloaded package.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Version mismatch between metadata and package"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Another update is already running.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Another update is in progress"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Update failed; rollback executed. `error` holds the exception message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Update failed and rollback executed"
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    },
                    "507": {
                        "description": "Insufficient disk space for backup + package.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Insufficient disk space"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/opening-stock/import/meta": {
            "get": {
                "operationId": "get_api_opening_stock_import_meta",
                "tags": [
                    "Products"
                ],
                "summary": "Get warehouses for opening-stock import",
                "description": "Returns the caller's `warehouses` so the opening-stock import screen can pick a target warehouse.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@opening_stock_meta",
                "x-source": "app/Http/Controllers/ProductsController.php#L4165-L4179",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "opening_stock_import",
                        "slug": "opening_stock_import",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/opening-stock/import/single": {
            "post": {
                "operationId": "post_api_opening_stock_import_single",
                "tags": [
                    "Products"
                ],
                "summary": "Import opening stock for single products",
                "description": "Adds opening quantities to existing single products in one warehouse from an `.xls`/`.xlsx` file with columns `product_code` and `qty`. The whole file is validated first (codes must exist, be unique in the file, quantities numeric); on success each quantity is **added** to `product_warehouse.qte` and one *Opening stock* adjustment is recorded so average-cost reports have a basis.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@opening_stock_import_single",
                "x-source": "app/Http/Controllers/ProductsController.php#L4182-L4312",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "opening_stock_import",
                        "slug": "opening_stock_import",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Product",
                    "product_warehouse",
                    "Adjustment",
                    "AdjustmentDetail"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:xls,xlsx",
                                        "x-laravel-rules": [
                                            "required",
                                            "mimes:xls,xlsx"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Spreadsheet file."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target warehouse."
                                    }
                                },
                                "required": [
                                    "products",
                                    "warehouse_id"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{status: true}` or `{status: false, message: \"Validation failed\", errors: [\"Row 3: …\"]}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Validation failed"
                                        },
                                        "errors": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/opening-stock/import/variants": {
            "post": {
                "operationId": "post_api_opening_stock_import_variants",
                "tags": [
                    "Products"
                ],
                "summary": "Import opening stock for variants",
                "description": "Same as the single opening-stock import but per variant: columns `product_code`, `variant_code`, `qty`. The variant must belong to the given product code.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@opening_stock_import_variants",
                "x-source": "app/Http/Controllers/ProductsController.php#L4315-L4455",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "opening_stock_import",
                        "slug": "opening_stock_import",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "product_warehouse",
                    "Adjustment",
                    "AdjustmentDetail"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:xls,xlsx",
                                        "x-laravel-rules": [
                                            "required",
                                            "mimes:xls,xlsx"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Spreadsheet file."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target warehouse."
                                    }
                                },
                                "required": [
                                    "products",
                                    "warehouse_id"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{status: true}` or `{status: false, message, errors[]}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Validation failed"
                                        },
                                        "errors": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/password/create": {
            "post": {
                "operationId": "post_api_password_create",
                "tags": [
                    "Authentication"
                ],
                "summary": "Request a password-reset email",
                "description": "Starts the forgotten-password flow for a staff user. If an **active** user with this email exists, a 60-character reset token is generated (replacing any previous one) and a link of the form `/password/find/{token}` is emailed using the mail settings configured in Stocky. The token is valid for 60 minutes.\n\nAlways responds with HTTP 200; unknown or inactive emails return `status: false`.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PasswordResetController@create",
                "x-source": "app/Http/Controllers/PasswordResetController.php#L22-L51",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "User",
                    "PasswordReset"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email address of the user who forgot their password."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "email": "admin@example.com"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`status: true` when the mail was sent; `status: false` + `message: \"We can't find a user with that e-mail address.\"` otherwise.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "We have e-mailed your password reset link!"
                                        }
                                    }
                                },
                                "example": {
                                    "status": true,
                                    "message": "We have e-mailed your password reset link!"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/api/password/reset": {
            "post": {
                "operationId": "post_api_password_reset",
                "tags": [
                    "Authentication"
                ],
                "summary": "Set a new password with a reset token",
                "description": "Completes the forgotten-password flow. The `token` comes from the reset email (`/password/find/{token}`); it must match the given `email`. On success the password is replaced, the token is deleted and a confirmation email is sent.\n\nAlways responds with HTTP 200; inspect `status` and `code`.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PasswordResetController@reset",
                "x-source": "app/Http/Controllers/PasswordResetController.php#L86-L126",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "User",
                    "PasswordReset"
                ],
                "x-notes": [
                    "The field `password_confirmation` is required by the `confirmed` rule even though it is not listed as a separate parameter."
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email of the account being reset; must match the email the token was issued for."
                                    },
                                    "password": {
                                        "type": "string",
                                        "x-rules": [
                                            "confirmed (send <field>_confirmation)"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "confirmed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New password. Must be repeated in `password_confirmation`."
                                    },
                                    "token": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Reset token from the email link."
                                    }
                                },
                                "required": [
                                    "email",
                                    "password",
                                    "token"
                                ]
                            },
                            "example": {
                                "email": "admin@example.com",
                                "token": "kQ2…60 chars…",
                                "password": "NewStr0ngPass!",
                                "password_confirmation": "NewStr0ngPass!"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`code: 1` success (returns the updated `user`); `code: 2` no user with that email; `code: 3` token invalid or does not belong to this email.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Your Password has been changed."
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "code": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "user": {}
                                    }
                                },
                                "example": {
                                    "status": true,
                                    "code": 1,
                                    "message": "Your Password has been changed.",
                                    "user": {
                                        "id": 1,
                                        "username": "William Castillo"
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/api/pay_purchase_return_due": {
            "post": {
                "operationId": "post_api_pay_purchase_return_due",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Receive a supplier's purchase-return refund",
                "description": "Records money received back from a supplier for **purchase returns** not yet refunded. The amount is spread over unpaid purchase returns in id order, creating `payment_purchase_returns` rows and updating each return's `paid_amount` / `payment_statut`. If `account_id` is given the account balance is **increased** (money in).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@pay_purchase_return_due",
                "x-source": "app/Http/Controllers/ProvidersController.php#L867-L926",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pay_purchase_return_due",
                        "slug": "pay_purchase_return_due",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "PaymentPurchaseReturns",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to credit (optional)."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Total amount received."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Note copied onto each generated payment."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id."
                                    },
                                    "provider_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Supplier refunding you."
                                    }
                                }
                            },
                            "example": {
                                "provider_id": 2,
                                "amount": 400,
                                "payment_method_id": 1
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pay_supplier_due": {
            "post": {
                "operationId": "post_api_pay_supplier_due",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Pay a supplier's outstanding due",
                "description": "Records a lump-sum payment to a supplier and allocates it automatically: the **opening balance** is settled first (creating a `provider_opening_balance_payments` row), then the remainder is applied to **received, not fully paid purchases** in id order, creating one `payment_purchases` row per purchase and updating `paid_amount` / `payment_statut`. If `account_id` is given the account balance is **decreased** (money out). Nothing happens when `amount <= 0`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@pay_supplier_due",
                "x-source": "app/Http/Controllers/ProvidersController.php#L766-L863",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pay_supplier_due",
                        "slug": "pay_supplier_due",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider",
                    "ProviderPaymentOpeningBalance",
                    "Account",
                    "Purchase",
                    "PaymentPurchase"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to debit (optional)."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Total amount paid."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Note copied onto each generated payment."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id."
                                    },
                                    "provider_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Supplier being paid."
                                    }
                                }
                            },
                            "example": {
                                "provider_id": 2,
                                "amount": 3000,
                                "payment_method_id": 2,
                                "account_id": 1,
                                "notes": "Wire #88"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_purchase": {
            "get": {
                "operationId": "get_api_payment_returns_purchase",
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "List purchase return refunds (report)",
                "description": "Paginated refunds between `from` and `to` (required). Rows: `id, date, Ref, purchase_return_Ref, provider_name, payment_method, account_name, montant, notes, created_by`. Returns `stats`, `timeseries`, `method_breakdown` and lookups.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@index",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L29-L189",
                "x-route-name": "returns_purchase.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_payments_purchase_Return",
                        "slug": "Reports_payments_purchase_Return",
                        "policy": "PaymentPurchaseReturnsPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "purchase_return_id",
                    "payment_method_id"
                ],
                "x-models": [
                    "PaymentPurchaseReturns",
                    "PaymentMethod",
                    "Provider",
                    "PurchaseReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (required)."
                    },
                    {
                        "name": "payment_method_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only this method."
                    },
                    {
                        "name": "provider_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this supplier."
                    },
                    {
                        "name": "purchase_return_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only refunds of this return."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]`, `totalRows`, `stats`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "amount": {
                                            "type": "number"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "method_breakdown": {},
                                        "purchase_returns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_payment_returns_purchase",
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "Record a refund on a purchase return",
                "description": "Creates a refund received from the supplier, **increases** the account balance and recomputes the return's `paid_amount` / `payment_statut`. Ignored when `montant` is `0`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@store",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L193-L257",
                "x-route-name": "returns_purchase.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "payment_returns_add",
                        "policy": "PaymentPurchaseReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "PaymentPurchaseReturns",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to credit."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount received.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Method id."
                                    },
                                    "purchase_return_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase return being refunded."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Create successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_purchase/Number/Order": {
            "get": {
                "operationId": "get_api_payment_returns_purchase_Number_Order",
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "Get the next refund reference",
                "description": "Returns the reference the next purchase-return refund will receive.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@getNumberOrder",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L426-L441",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Plain string reference.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_purchase/send/email": {
            "post": {
                "operationId": "post_api_payment_returns_purchase_send_email",
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "Email a refund receipt",
                "description": "Generates the refund PDF and emails it to `to`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@SendEmail",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L406-L422",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_returns_view",
                        "policy": "PaymentPurchaseReturnsPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "x-response-type": "file",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "Ref": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference shown in the email."
                                    },
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Refund id."
                                    },
                                    "to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Recipient email address.",
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_purchase/send/sms": {
            "post": {
                "operationId": "post_api_payment_returns_purchase_send_sms",
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "SMS a refund notice to the supplier",
                "description": "Sends a fixed notification with a link to the refund PDF through the default SMS gateway.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@Send_SMS",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L484-L556",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "PaymentPurchaseReturns",
                    "Setting",
                    "sms_gateway"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Refund id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_purchase/{returns_purchase}": {
            "delete": {
                "operationId": "delete_api_payment_returns_purchase_returns_purchase",
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "Delete a refund",
                "description": "Soft-deletes the refund, reverses the account balance and recomputes the return's paid status.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@destroy",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L347-L402",
                "x-route-name": "returns_purchase.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "payment_returns_delete",
                        "policy": "PaymentPurchaseReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentPurchaseReturns",
                    "PurchaseReturn",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "returns_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Delete successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_payment_returns_purchase_returns_purchase",
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "(Not implemented) Get a refund",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/returns/purchase/payment/{id}`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@show",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L261-L265",
                "x-route-name": "returns_purchase.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "returns_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_payment_returns_purchase_returns_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "Update a refund",
                "description": "Re-balances accounts and recomputes the return's paid status.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@update",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L269-L343",
                "x-route-name": "returns_purchase.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_returns_edit",
                        "policy": "PaymentPurchaseReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentPurchaseReturns",
                    "PurchaseReturn",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "returns_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Method id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_payment_returns_purchase_returns_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchase Return Payments"
                ],
                "summary": "Update a refund",
                "description": "Re-balances accounts and recomputes the return's paid status.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchaseReturnsController@update",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L269-L343",
                "x-route-name": "returns_purchase.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_returns_edit",
                        "policy": "PaymentPurchaseReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentPurchaseReturns",
                    "PurchaseReturn",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "returns_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Method id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/payment/returns_sale": {
            "get": {
                "operationId": "get_api_payment_returns_sale",
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "List sale return refunds (report)",
                "description": "Paginated refunds between `from` and `to` (required), scoped like sale payments. Rows: `id, date, Ref, Sale_Return_Ref, client_name, payment_method, account_name, montant, notes, created_by`. Returns `stats`, `timeseries`, `method_breakdown` and lookups (`sale_returns`, `clients`, `payment_methods`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@index",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L29-L189",
                "x-route-name": "returns_sale.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_payments_Sale_Returns",
                        "slug": "Reports_payments_Sale_Returns",
                        "policy": "PaymentSaleReturnsPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "sale_return_id",
                    "payment_method_id"
                ],
                "x-models": [
                    "PaymentSaleReturns",
                    "PaymentMethod",
                    "Client",
                    "SaleReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this customer."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (required)."
                    },
                    {
                        "name": "payment_method_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only this method."
                    },
                    {
                        "name": "sale_return_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only refunds of this return."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]`, `totalRows`, `stats`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "amount": {
                                            "type": "number"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "method_breakdown": {},
                                        "sale_returns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_payment_returns_sale",
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "Record a refund on a sale return",
                "description": "Creates a refund against a sale return, **decreases** the account balance and recomputes the return's `paid_amount` / `payment_statut`. Ignored when `montant` is `0`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@store",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L193-L257",
                "x-route-name": "returns_sale.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "payment_returns_add",
                        "policy": "PaymentSaleReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "PaymentSaleReturns",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to debit."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount refunded.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id."
                                    },
                                    "sale_return_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale return being refunded."
                                    }
                                }
                            },
                            "example": {
                                "sale_return_id": 7,
                                "date": "2026-09-07",
                                "montant": 19.9,
                                "payment_method_id": 1,
                                "account_id": 1,
                                "change": 0
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Create successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_sale/Number/order": {
            "get": {
                "operationId": "get_api_payment_returns_sale_Number_order",
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "Get the next refund reference",
                "description": "Returns the reference the next sale-return refund will receive (e.g. `INV/RT_1112`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@getNumberOrder",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L407-L421",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Plain string reference.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_sale/send/email": {
            "post": {
                "operationId": "post_api_payment_returns_sale_send_email",
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "Email a refund receipt",
                "description": "Generates the refund PDF and emails it to the address in `to`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@SendEmail",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L425-L441",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_returns_view",
                        "policy": "PaymentSaleReturnsPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "x-response-type": "file",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "Ref": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Refund reference shown in the email."
                                    },
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Refund id."
                                    },
                                    "to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Recipient email address.",
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_sale/send/sms": {
            "post": {
                "operationId": "post_api_payment_returns_sale_send_sms",
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "SMS a refund notice to the customer",
                "description": "Sends a fixed notification text with a link to the refund PDF through the default SMS gateway.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@Send_SMS",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L485-L556",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "PaymentSaleReturns",
                    "Setting",
                    "sms_gateway"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Refund id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment/returns_sale/{returns_sale}": {
            "delete": {
                "operationId": "delete_api_payment_returns_sale_returns_sale",
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "Delete a refund",
                "description": "Soft-deletes the refund, restores the account balance and recomputes the return's paid status.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@destroy",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L347-L403",
                "x-route-name": "returns_sale.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "payment_returns_delete",
                        "policy": "PaymentSaleReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentSaleReturns",
                    "SaleReturn",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "returns_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Delete successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_payment_returns_sale_returns_sale",
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "(Not implemented) Get a refund",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/returns/sale/payment/{id}`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@show",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L261-L265",
                "x-route-name": "returns_sale.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "returns_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_payment_returns_sale_returns_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "Update a refund",
                "description": "Re-balances the accounts (old amount restored, new amount debited) and recomputes the return's paid status.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@update",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L269-L343",
                "x-route-name": "returns_sale.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_returns_edit",
                        "policy": "PaymentSaleReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentSaleReturns",
                    "SaleReturn",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "returns_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Method id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_payment_returns_sale_returns_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sale Return Payments"
                ],
                "summary": "Update a refund",
                "description": "Re-balances the accounts (old amount restored, new amount debited) and recomputes the return's paid status.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSaleReturnsController@update",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L269-L343",
                "x-route-name": "returns_sale.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_returns_edit",
                        "policy": "PaymentSaleReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentSaleReturns",
                    "SaleReturn",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "returns_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Refund id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Method id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/payment_gateway": {
            "post": {
                "operationId": "post_api_payment_gateway",
                "tags": [
                    "Payment Gateway Settings"
                ],
                "summary": "Update Stripe config",
                "description": "Writes `STRIPE_KEY`/`STRIPE_SECRET` to `.env` and rebuilds the config cache. Send `deleted=true` to clear both keys. A `null` secret keeps the current one.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Payment_gateway_SettingsController@Update_payment_gateway",
                "x-source": "app/Http/Controllers/Payment_gateway_SettingsController.php#L41-L63",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "payment_gateway",
                        "slug": "payment_gateway | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "deleted": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` to remove the Stripe configuration.",
                                        "type": "boolean"
                                    },
                                    "stripe_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Publishable key."
                                    },
                                    "stripe_secret": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Secret key."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_methods": {
            "get": {
                "operationId": "get_api_payment_methods",
                "tags": [
                    "Payment Methods"
                ],
                "summary": "List payment methods",
                "description": "Paginated payment methods (`id, name, is_active`); `search` matches the name.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "PaymentMethodController@index",
                "x-source": "app/Http/Controllers/PaymentMethodController.php#L14-L47",
                "x-route-name": "payment_methods.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_methods",
                        "policy": "PaymentMethodPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`methods[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_payment_methods",
                "tags": [
                    "Payment Methods"
                ],
                "summary": "Create a payment method",
                "description": "Creates an active payment method.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "PaymentMethodController@store",
                "x-source": "app/Http/Controllers/PaymentMethodController.php#L51-L64",
                "x-route-name": "payment_methods.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "payment_methods",
                        "policy": "PaymentMethodPolicy"
                    }
                ],
                "x-models": [
                    "PaymentMethod"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Method name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_methods/{id}/active": {
            "put": {
                "operationId": "put_api_payment_methods_id_active",
                "tags": [
                    "Payment Methods"
                ],
                "summary": "Activate or deactivate a payment method",
                "description": "Toggles `is_active`. Inactive methods are hidden from new-payment pickers but remain in history and reports.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "PaymentMethodController@setActive",
                "x-source": "app/Http/Controllers/PaymentMethodController.php#L100-L113",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_methods",
                        "policy": "PaymentMethodPolicy"
                    }
                ],
                "x-models": [
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Method id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`true` or `false`."
                                    }
                                },
                                "required": [
                                    "is_active"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_methods/{payment_method}": {
            "delete": {
                "operationId": "delete_api_payment_methods_payment_method",
                "tags": [
                    "Payment Methods"
                ],
                "summary": "Delete a payment method",
                "description": "Soft-deletes the method.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "PaymentMethodController@destroy",
                "x-source": "app/Http/Controllers/PaymentMethodController.php#L117-L126",
                "x-route-name": "payment_methods.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "payment_methods",
                        "policy": "PaymentMethodPolicy"
                    }
                ],
                "x-models": [
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Method id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_payment_methods_payment_method",
                "tags": [
                    "Payment Methods"
                ],
                "summary": "(Not implemented) Get a payment method",
                "description": "Empty stub; returns an empty `200`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "PaymentMethodController@show",
                "x-source": "app/Http/Controllers/PaymentMethodController.php#L68-L72",
                "x-route-name": "payment_methods.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Method id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_payment_methods_payment_method",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Payment Methods"
                ],
                "summary": "Rename a payment method",
                "description": "Renames the method (default methods 1–3 are protected in the UI).",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "PaymentMethodController@update",
                "x-source": "app/Http/Controllers/PaymentMethodController.php#L76-L90",
                "x-route-name": "payment_methods.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_methods",
                        "policy": "PaymentMethodPolicy"
                    }
                ],
                "x-models": [
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Method id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_payment_methods_payment_method",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Payment Methods"
                ],
                "summary": "Rename a payment method",
                "description": "Renames the method (default methods 1–3 are protected in the UI).",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "PaymentMethodController@update",
                "x-source": "app/Http/Controllers/PaymentMethodController.php#L76-L90",
                "x-route-name": "payment_methods.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_methods",
                        "policy": "PaymentMethodPolicy"
                    }
                ],
                "x-models": [
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "payment_method",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Method id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/payment_purchase": {
            "get": {
                "operationId": "get_api_payment_purchase",
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "List purchase payments (report)",
                "description": "Paginated payments between `from` and `to` (both required), scoped to the caller's warehouses and record view. Rows: `id, date, Ref, purchase_Ref, provider_name, payment_method, account_name, montant, change, notes, created_by`. `search` matches Ref, date, supplier name, purchase Ref and payment method. Also returns `stats`, `timeseries`, `method_breakdown` and the `purchases`, `suppliers`, `payment_methods` lookups.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@index",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L37-L197",
                "x-route-name": "payment_purchase.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_payments_Purchases",
                        "slug": "Reports_payments_Purchases",
                        "policy": "PaymentPurchasePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "purchase_id",
                    "payment_method_id"
                ],
                "x-models": [
                    "PaymentPurchase",
                    "PaymentMethod",
                    "Provider",
                    "Purchase"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (required)."
                    },
                    {
                        "name": "payment_method_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only this method."
                    },
                    {
                        "name": "provider_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this supplier."
                    },
                    {
                        "name": "purchase_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only payments of this purchase."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]`, `totalRows`, `stats`, `timeseries`, `method_breakdown`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "amount": {
                                            "type": "number"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "method_breakdown": {},
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_payment_purchase",
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "Record a payment on a purchase",
                "description": "Creates a payment against a purchase, **decreases** the treasury account balance and recomputes the purchase's `paid_amount` / `payment_statut`. Ignored when `montant` is `0`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@store",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L201-L265",
                "x-route-name": "payment_purchase.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "payment_purchases_add",
                        "policy": "PaymentPurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "PaymentPurchase",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to debit."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount paid.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id."
                                    },
                                    "purchase_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase being paid."
                                    }
                                }
                            },
                            "example": {
                                "purchase_id": 12,
                                "date": "2026-09-06",
                                "montant": 500,
                                "payment_method_id": 2,
                                "account_id": 1,
                                "change": 0,
                                "notes": "Wire #88"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Create successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_purchase/{payment_purchase}": {
            "delete": {
                "operationId": "delete_api_payment_purchase_payment_purchase",
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "Delete a purchase payment",
                "description": "Soft-deletes the payment, credits the amount back to the account and recomputes the purchase's paid status.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@destroy",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L354-L410",
                "x-route-name": "payment_purchase.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "payment_purchases_delete",
                        "policy": "PaymentPurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentPurchase",
                    "Purchase",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payment_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Delete successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_payment_purchase_payment_purchase",
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "(Not implemented) Get a purchase payment",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/get_payments_by_purchase/{id}`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@show",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L269-L273",
                "x-route-name": "payment_purchase.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "payment_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_payment_purchase_payment_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "Update a purchase payment",
                "description": "Re-balances accounts (old amount credited back, new amount debited) and recomputes the purchase's paid status. `purchase_id` must be sent so the purchase can be updated.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@update",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L277-L350",
                "x-route-name": "payment_purchase.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_purchases_edit",
                        "policy": "PaymentPurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentPurchase",
                    "Purchase",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payment_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Method id."
                                    },
                                    "purchase_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase the payment belongs to."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_payment_purchase_payment_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "Update a purchase payment",
                "description": "Re-balances accounts (old amount credited back, new amount debited) and recomputes the purchase's paid status. `purchase_id` must be sent so the purchase can be updated.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@update",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L277-L350",
                "x-route-name": "payment_purchase.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_purchases_edit",
                        "policy": "PaymentPurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentPurchase",
                    "Purchase",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payment_purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Method id."
                                    },
                                    "purchase_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase the payment belongs to."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/payment_purchase_get_number": {
            "get": {
                "operationId": "get_api_payment_purchase_get_number",
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "Get the next payment reference",
                "description": "Returns the reference the next purchase payment will receive (e.g. `INV/PR_1120`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@getNumberOrder",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L414-L428",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Plain string reference.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_purchase_pdf/{id}": {
            "get": {
                "operationId": "get_api_payment_purchase_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Purchase payment receipt PDF",
                "description": "Receipt for one supplier payment: purchase reference, supplier block, amount, method and date. Public route (no token).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PaymentPurchasesController@Payment_purchase_pdf",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L432-L468",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "PaymentPurchase",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase payment ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/payment_purchase_send_email": {
            "post": {
                "operationId": "post_api_payment_purchase_send_email",
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "Email a payment notice to the supplier",
                "description": "Sends the *payment_sent* email template with `{contact_name}`, `{business_name}`, `{payment_number}`, `{total_amount}`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@SendEmail",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L472-L522",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_purchases_view",
                        "policy": "PaymentPurchasePolicy"
                    }
                ],
                "x-models": [
                    "PaymentPurchase",
                    "Setting",
                    "EmailMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_purchase_send_sms": {
            "post": {
                "operationId": "post_api_payment_purchase_send_sms",
                "tags": [
                    "Purchase Payments"
                ],
                "summary": "SMS a payment notice to the supplier",
                "description": "Sends the *payment_sent* SMS template through the default gateway.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PaymentPurchasesController@Send_SMS",
                "x-source": "app/Http/Controllers/PaymentPurchasesController.php#L526-L657",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_purchases_view",
                        "policy": "PaymentPurchasePolicy"
                    }
                ],
                "x-models": [
                    "PaymentPurchase",
                    "Setting",
                    "sms_gateway",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_return_purchase_pdf/{id}": {
            "get": {
                "operationId": "get_api_payment_return_purchase_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Purchase-return payment receipt PDF",
                "description": "Receipt for one refund received on a purchase return. Public route (no token).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PaymentPurchaseReturnsController@payment_return",
                "x-source": "app/Http/Controllers/PaymentPurchaseReturnsController.php#L445-L481",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "PaymentPurchaseReturns",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase-return payment ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/payment_return_sale_pdf/{id}": {
            "get": {
                "operationId": "get_api_payment_return_sale_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Sale-return payment receipt PDF",
                "description": "Receipt for one refund paid on a sale return. Public route (no token).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PaymentSaleReturnsController@payment_return",
                "x-source": "app/Http/Controllers/PaymentSaleReturnsController.php#L445-L482",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "PaymentSaleReturns",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale-return payment ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/payment_returns_client": {
            "get": {
                "operationId": "get_api_payment_returns_client",
                "tags": [
                    "Customers"
                ],
                "summary": "List a customer's return refunds (ledger)",
                "description": "Paginated refunds paid against the customer's sale returns, newest first. Rows: `id, date, Ref, Sale_Return_Ref, payment_method, montant`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@paymentReturnsByClient",
                "x-source": "app/Http/Controllers/ClientController.php#L1432-L1486",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "x-exists": "clients,id",
                            "x-laravel-rules": [
                                "required",
                                "integer",
                                "exists:clients,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Customer id (query string, required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payment_returns[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payment_returns": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_sale": {
            "get": {
                "operationId": "get_api_payment_sale",
                "tags": [
                    "Sale Payments"
                ],
                "summary": "List sale payments (report)",
                "description": "Paginated payments between `from` and `to` (both required, `YYYY-MM-DD`), scoped to the caller's warehouses and record view. Rows: `id, date, Ref, Sale_Ref, client_name, payment_method, account_name, montant, change, notes, created_by`. `search` matches Ref, date, customer name, sale Ref and payment method. Also returns `stats` (count, total), `timeseries` (per-day totals), `method_breakdown` and the `sales`, `clients`, `payment_methods` lookups.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@index",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L37-L197",
                "x-route-name": "payment_sale.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_payments_Sales",
                        "slug": "Reports_payments_Sales",
                        "policy": "PaymentSalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "sale_id",
                    "payment_method_id"
                ],
                "x-models": [
                    "PaymentSale",
                    "PaymentMethod",
                    "Client",
                    "Sale"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on payment reference."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only payments of this customer."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (required)."
                    },
                    {
                        "name": "payment_method_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only this payment method."
                    },
                    {
                        "name": "sale_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only payments of this sale."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]`, `totalRows`, `stats`, `timeseries`, `method_breakdown`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "amount": {
                                            "type": "number"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "method_breakdown": {},
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_payment_sale",
                "tags": [
                    "Sale Payments"
                ],
                "summary": "Record a payment on a sale",
                "description": "Adds one or more payments to a sale. Send `payments[]` for split payments (one row per method), or the legacy single fields `montant` + `payment_method_id` + `account_id` + `change`. The sale's `paid_amount` and `payment_statut` are recomputed and each account balance increased. Nothing is written when the amount is `0`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@store",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L201-L310",
                "x-route-name": "payment_sale.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "payment_sales_add",
                        "policy": "PaymentSalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "PaymentSale",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to credit."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cash change returned.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount (single-payment form).",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Note stored on every payment row."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id (single-payment form / default for lines)."
                                    },
                                    "payments": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Split payments: `[{montant, payment_method_id, account_id, change}]`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale being paid."
                                    }
                                }
                            },
                            "example": {
                                "sale_id": 41,
                                "date": "2026-09-06",
                                "payments": [
                                    {
                                        "montant": 20,
                                        "payment_method_id": 1,
                                        "account_id": 1,
                                        "change": 0
                                    },
                                    {
                                        "montant": 19.8,
                                        "payment_method_id": 2,
                                        "account_id": 2,
                                        "change": 0
                                    }
                                ],
                                "notes": "Split cash + card"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Create successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Error message (e.g. failed card charge).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_sale/{payment_sale}": {
            "delete": {
                "operationId": "delete_api_payment_sale_payment_sale",
                "tags": [
                    "Sale Payments"
                ],
                "summary": "Delete a sale payment",
                "description": "Soft-deletes the payment, reduces the account balance by its amount and recomputes the sale's paid amount / status.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@destroy",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L409-L465",
                "x-route-name": "payment_sale.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "payment_sales_delete",
                        "policy": "PaymentSalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentSale",
                    "Sale",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payment_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Delete successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_payment_sale_payment_sale",
                "tags": [
                    "Sale Payments"
                ],
                "summary": "(Not implemented) Get a sale payment",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/get_payments_by_sale/{id}`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@show",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L314-L318",
                "x-route-name": "payment_sale.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "payment_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_payment_sale_payment_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sale Payments"
                ],
                "summary": "Update a sale payment",
                "description": "Changes date, method, account, amount, change and notes of one payment; the old amount is removed from the old account and the new amount added to the new one, and the sale's paid amount / status are recomputed. Payments made by card through Stripe (method id 1 in older setups) are not editable.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@update",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L322-L405",
                "x-route-name": "payment_sale.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_sales_edit",
                        "policy": "PaymentSalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentSale",
                    "Sale",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payment_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "New amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_payment_sale_payment_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sale Payments"
                ],
                "summary": "Update a sale payment",
                "description": "Changes date, method, account, amount, change and notes of one payment; the old amount is removed from the old account and the new amount added to the new one, and the sale's paid amount / status are recomputed. Payments made by card through Stripe (method id 1 in older setups) are not editable.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@update",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L322-L405",
                "x-route-name": "payment_sale.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payment_sales_edit",
                        "policy": "PaymentSalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PaymentSale",
                    "Sale",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payment_sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account id."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change.",
                                        "type": "number"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "New amount.",
                                        "type": "number"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment method id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Payment Update successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/payment_sale_get_number": {
            "get": {
                "operationId": "get_api_payment_sale_get_number",
                "tags": [
                    "Sale Payments"
                ],
                "summary": "Get the next payment reference",
                "description": "Returns the reference the next sale payment will receive (e.g. `INV/SL_1125`), derived from the last payment.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@getNumberOrder",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L469-L500",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Plain string reference.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_sale_pdf/{id}": {
            "get": {
                "operationId": "get_api_payment_sale_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Sale payment receipt PDF",
                "description": "Receipt for one customer payment: sale reference, customer, amount, method and date.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PaymentSalesController@payment_sale",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L504-L540",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "PaymentSale",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale payment ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/payment_sale_send_email": {
            "post": {
                "operationId": "post_api_payment_sale_send_email",
                "tags": [
                    "Sale Payments"
                ],
                "summary": "Email a payment receipt to the customer",
                "description": "Sends the *payment_received* email template with `{contact_name}`, `{business_name}`, `{payment_number}`, `{total_amount}`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@SendEmail",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L544-L594",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_sales_view",
                        "policy": "PaymentSalePolicy"
                    }
                ],
                "x-models": [
                    "PaymentSale",
                    "Setting",
                    "EmailMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payment_sale_send_sms": {
            "post": {
                "operationId": "post_api_payment_sale_send_sms",
                "tags": [
                    "Sale Payments"
                ],
                "summary": "SMS a payment receipt to the customer",
                "description": "Sends the *payment_received* SMS template through the default gateway.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "PaymentSalesController@Send_SMS",
                "x-source": "app/Http/Controllers/PaymentSalesController.php#L598-L729",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_sales_view",
                        "policy": "PaymentSalePolicy"
                    }
                ],
                "x-models": [
                    "PaymentSale",
                    "Setting",
                    "sms_gateway",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payments_client": {
            "get": {
                "operationId": "get_api_payments_client",
                "tags": [
                    "Customers"
                ],
                "summary": "List a customer's payments (ledger)",
                "description": "Paginated list merging **sale payments** and **opening-balance payments** for one customer, newest first. Each row has `id, date, Ref, Sale_Ref (or null), payment_method, montant, payment_type` where `payment_type` is `sale` or `opening_balance`. `search` matches payment ref, date and payment-method name.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@paymentsByClient",
                "x-source": "app/Http/Controllers/ClientController.php#L1005-L1098",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "x-exists": "clients,id",
                            "x-laravel-rules": [
                                "required",
                                "integer",
                                "exists:clients,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Customer id (query string, required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "totalRows": 1,
                                    "payments": [
                                        {
                                            "id": 9,
                                            "date": "2026-09-02",
                                            "Ref": "INV/PY_1109",
                                            "Sale_Ref": "SL_1120",
                                            "payment_method": "Cash",
                                            "montant": 300,
                                            "payment_type": "sale"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payroll": {
            "get": {
                "operationId": "get_api_payroll",
                "tags": [
                    "Payroll"
                ],
                "summary": "List payroll payments",
                "description": "Paginated rows `id, Ref, account_id, employee_id, account_name, employee_name, date, amount, payment_method_id, payment_status` plus the lookups `accounts`, `employees` and active `payment_methods`. `search` matches Ref, account name or employee username.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@index",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L19-L86",
                "x-route-name": "payroll.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payroll",
                        "policy": "PayrollPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Payroll",
                    "Account",
                    "Employee",
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payrolls[]`, `totalRows`, `accounts[]`, `employees[]`, `payment_methods[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payrolls": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_payroll",
                "tags": [
                    "Payroll"
                ],
                "summary": "Create a payroll payment",
                "description": "Creates a `paid` payroll with a generated `Ref` and debits the treasury account when `account_id` is given.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@store",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L95-L132",
                "x-route-name": "payroll.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "payroll",
                        "policy": "PayrollPolicy"
                    }
                ],
                "x-models": [
                    "Payroll",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account to debit (optional)."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount paid."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Payment date."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Payment method."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "date",
                                    "employee_id",
                                    "payment_method_id"
                                ]
                            },
                            "example": {
                                "date": "2026-09-01",
                                "employee_id": 7,
                                "amount": 4500,
                                "payment_method_id": 2,
                                "account_id": 1
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payroll/create": {
            "get": {
                "operationId": "get_api_payroll_create",
                "tags": [
                    "Payroll"
                ],
                "summary": "Create-form data for payroll (not implemented)",
                "description": "**Not implemented** — the list endpoint already returns the lookups.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@create",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L88-L91",
                "x-route-name": "payroll.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/payroll/{payroll}": {
            "delete": {
                "operationId": "delete_api_payroll_payroll",
                "tags": [
                    "Payroll"
                ],
                "summary": "Delete a payroll payment",
                "description": "Soft-deletes and credits the amount back to the linked account.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@destroy",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L202-L225",
                "x-route-name": "payroll.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "payroll",
                        "policy": "PayrollPolicy"
                    }
                ],
                "x-models": [
                    "Payroll",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payroll",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payroll id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_payroll_payroll",
                "tags": [
                    "Payroll"
                ],
                "summary": "Get a payroll (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@show",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L136-L140",
                "x-route-name": "payroll.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "payroll",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payroll id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_payroll_payroll",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Payroll"
                ],
                "summary": "Update a payroll payment",
                "description": "Restores the previous amount to the old account, updates the row, then debits the new account.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@update",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L150-L198",
                "x-route-name": "payroll.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payroll",
                        "policy": "PayrollPolicy"
                    }
                ],
                "x-models": [
                    "Payroll",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payroll",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payroll id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Payment method."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "date",
                                    "employee_id",
                                    "payment_method_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_payroll_payroll",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Payroll"
                ],
                "summary": "Update a payroll payment",
                "description": "Restores the previous amount to the old account, updates the row, then debits the new account.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@update",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L150-L198",
                "x-route-name": "payroll.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "payroll",
                        "policy": "PayrollPolicy"
                    }
                ],
                "x-models": [
                    "Payroll",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "payroll",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payroll id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Treasury account."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "payment_method_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Payment method."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "date",
                                    "employee_id",
                                    "payment_method_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/payroll/{payroll}/edit": {
            "get": {
                "operationId": "get_api_payroll_payroll_edit",
                "tags": [
                    "Payroll"
                ],
                "summary": "Edit-form data for payroll (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\PayrollController@edit",
                "x-source": "app/Http/Controllers/hrm/PayrollController.php#L142-L146",
                "x-route-name": "payroll.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "payroll",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Payroll id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pdf_templates/{type}": {
            "get": {
                "operationId": "get_api_pdf_templates_type",
                "tags": [
                    "PDF Templates"
                ],
                "summary": "Get PDF template settings",
                "description": "Saved settings for one document type merged over the built-in defaults, plus the defaults themselves so the UI can offer a reset.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "PdfTemplateController@show",
                "x-source": "app/Http/Controllers/PdfTemplateController.php#L12-L21",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PdfTemplate"
                ],
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "sale",
                                "quotation",
                                "purchase"
                            ]
                        },
                        "description": "Document type."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{settings: {...}, defaults: {...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {},
                                        "defaults": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_pdf_templates_type",
                "tags": [
                    "PDF Templates"
                ],
                "summary": "Save PDF template settings",
                "description": "Save the settings for one document type.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "PdfTemplateController@update",
                "x-source": "app/Http/Controllers/PdfTemplateController.php#L24-L63",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PdfTemplate"
                ],
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Document type."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "background_color": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Page background colour."
                                    },
                                    "font_family": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "DejaVu Sans",
                                            "DejaVu Serif",
                                            "DejaVu Sans Mono",
                                            "Helvetica",
                                            "Times",
                                            "Courier"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:DejaVu Sans,DejaVu Serif,DejaVu Sans Mono,Helvetica,Times,Courier"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Font (DejaVu fonts support Arabic/Unicode)."
                                    },
                                    "font_size": {
                                        "type": "integer",
                                        "minimum": 7,
                                        "maximum": 14,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:7",
                                            "max:14"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Base font size in pt (7–14)."
                                    },
                                    "footer_text": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Footer text (max 1000)."
                                    },
                                    "labels": {
                                        "type": "object",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Optional label overrides.",
                                        "properties": {
                                            "thank_you": {
                                                "type": "string",
                                                "maxLength": 190,
                                                "nullable": true,
                                                "x-laravel-rules": [
                                                    "nullable",
                                                    "string",
                                                    "max:190"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Thank-you line text."
                                            },
                                            "title": {
                                                "type": "string",
                                                "maxLength": 120,
                                                "nullable": true,
                                                "x-laravel-rules": [
                                                    "nullable",
                                                    "string",
                                                    "max:120"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Document title (e.g. `Tax Invoice`)."
                                            }
                                        }
                                    },
                                    "logo_height": {
                                        "type": "integer",
                                        "minimum": 20,
                                        "maximum": 300,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:20",
                                            "max:300"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Logo height in px (20–300)."
                                    },
                                    "logo_show": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Print the company logo."
                                    },
                                    "logo_width": {
                                        "type": "integer",
                                        "minimum": 40,
                                        "maximum": 400,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:40",
                                            "max:400"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Logo width in px (40–400)."
                                    },
                                    "margin_h": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 40,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:0",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Horizontal page margin in mm (0–40)."
                                    },
                                    "margin_v": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 40,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:0",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Vertical page margin in mm (0–40)."
                                    },
                                    "primary_color": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Header/accent colour (hex)."
                                    },
                                    "secondary_color": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Secondary accent colour (hex)."
                                    },
                                    "show_company": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show the company block."
                                    },
                                    "show_customer": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show the customer/supplier block."
                                    },
                                    "show_footer_text": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Print `footer_text`."
                                    },
                                    "show_notes": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Print the document note."
                                    },
                                    "show_status": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show the document status badge."
                                    },
                                    "show_thank_you": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Print the thank-you line."
                                    },
                                    "table_borders": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Draw borders around line-item cells."
                                    },
                                    "table_striped": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Alternate row shading."
                                    },
                                    "text_color": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Body text colour."
                                    }
                                },
                                "required": [
                                    "background_color",
                                    "font_family",
                                    "font_size",
                                    "logo_height",
                                    "logo_show",
                                    "logo_width",
                                    "margin_h",
                                    "margin_v",
                                    "primary_color",
                                    "secondary_color",
                                    "show_company",
                                    "show_customer",
                                    "show_footer_text",
                                    "show_notes",
                                    "show_status",
                                    "show_thank_you",
                                    "table_borders",
                                    "table_striped",
                                    "text_color"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pending-work": {
            "get": {
                "operationId": "get_api_pending_work",
                "tags": [
                    "Dashboard"
                ],
                "summary": "Get pending work items",
                "description": "Counts of things awaiting action across modules (product quantity alerts, pending online orders, payment proofs to verify, pending customers, return requests, quote requests, product reviews, customer questions, messages, pending withdrawals…). Sources the user may not view, or whose tables are missing on this install, are skipped.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "Api\\PendingWorkController@index",
                "x-source": "app/Http/Controllers/Api/PendingWorkController.php#L32-L74",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`{items: [{key, label, count, route}], total}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/ping": {
            "get": {
                "operationId": "get_api_ping",
                "tags": [
                    "Health & Utilities"
                ],
                "summary": "Reachability probe",
                "description": "Lightweight probe the admin SPA polls to detect that the server is online (offline-mode detection). Returns no sensitive data.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "`ok` is always `true`; `ts` is the server Unix timestamp."
                    }
                },
                "security": []
            }
        },
        "/api/portal/appointments": {
            "get": {
                "operationId": "get_api_portal_appointments",
                "tags": [
                    "Portal Appointments"
                ],
                "summary": "List my appointments",
                "description": "Service jobs of the client, newest scheduled first. `search` matches Ref, item, issue or status.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalAppointmentsController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAppointmentsController.php#L16-L63",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-paginated": true,
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`appointments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "Ref": {},
                                        "service_item": {},
                                        "job_type": {},
                                        "status": {},
                                        "scheduled_date": {
                                            "type": "string"
                                        },
                                        "reported_issue": {},
                                        "total_amount": {
                                            "type": "number"
                                        },
                                        "paid_amount": {
                                            "type": "number"
                                        },
                                        "payment_status": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "appointments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_portal_appointments",
                "tags": [
                    "Portal Appointments"
                ],
                "summary": "Book an appointment",
                "description": "POST /api/portal/appointments - client books a new appointment. Creates a ServiceJob with status='pending' for admins to confirm/schedule. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalAppointmentsController@store",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAppointmentsController.php#L107-L162",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "ServiceJob"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "device_brand": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Brand."
                                    },
                                    "device_model": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Model."
                                    },
                                    "device_serial": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Serial."
                                    },
                                    "job_type": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Type."
                                    },
                                    "reported_issue": {
                                        "type": "string",
                                        "maxLength": 5000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:5000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Problem description."
                                    },
                                    "scheduled_date": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Requested date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "service_item": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Item to service."
                                    }
                                },
                                "required": [
                                    "scheduled_date",
                                    "service_item"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success`, `id`, `Ref`, `service_item`, `status`, `scheduled_date`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "Ref": {},
                                        "service_item": {},
                                        "status": {},
                                        "scheduled_date": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/appointments/{id}": {
            "get": {
                "operationId": "get_api_portal_appointments_id",
                "tags": [
                    "Portal Appointments"
                ],
                "summary": "Get my appointment",
                "description": "GET /api/portal/appointments/{id} - appointment detail. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalAppointmentsController@show",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAppointmentsController.php#L68-L101",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Service job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Appointment object (dates, issue, diagnosis, technician, amounts).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "Ref": {},
                                        "service_item": {},
                                        "job_type": {},
                                        "status": {},
                                        "scheduled_date": {
                                            "type": "string"
                                        },
                                        "started_at": {
                                            "type": "string"
                                        },
                                        "completed_at": {
                                            "type": "string"
                                        },
                                        "created_at": {
                                            "type": "string"
                                        },
                                        "reported_issue": {},
                                        "diagnosis": {},
                                        "notes": {},
                                        "device_brand": {},
                                        "device_model": {},
                                        "device_serial": {},
                                        "technician_name": {},
                                        "quote_amount": {
                                            "type": "number"
                                        },
                                        "total_amount": {
                                            "type": "number"
                                        },
                                        "paid_amount": {
                                            "type": "number"
                                        },
                                        "payment_status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/contracts": {
            "get": {
                "operationId": "get_api_portal_contracts",
                "tags": [
                    "Portal Contracts"
                ],
                "summary": "List my contracts",
                "description": "GET /api/portal/contracts - list this client's contracts (excluding hide_from_customer). /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalContractsController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalContractsController.php#L17-L65",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-paginated": true,
                "x-models": [
                    "Contract"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`contracts[] {id, contract_number, subject, type, value, start_date, end_date, status, signed_at}` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "contract_number": {},
                                        "subject": {},
                                        "type": {},
                                        "value": {
                                            "type": "number"
                                        },
                                        "start_date": {},
                                        "end_date": {},
                                        "status": {},
                                        "signed_at": {
                                            "type": "string"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "contracts": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/contracts/{id}": {
            "get": {
                "operationId": "get_api_portal_contracts_id",
                "tags": [
                    "Portal Contracts"
                ],
                "summary": "Get my contract",
                "description": "GET /api/portal/contracts/{id} - contract detail with attachments. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalContractsController@show",
                "x-source": "app/Http/Controllers/Api/Portal/PortalContractsController.php#L70-L95",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Contract with `attachments[] {id, file_name}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "contract_number": {},
                                        "subject": {},
                                        "description": {},
                                        "type": {},
                                        "value": {
                                            "type": "number"
                                        },
                                        "start_date": {},
                                        "end_date": {},
                                        "status": {},
                                        "signer_name": {},
                                        "signed_at": {
                                            "type": "string"
                                        },
                                        "attachments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/contracts/{id}/attachments/{attachmentId}/download": {
            "get": {
                "operationId": "get_api_portal_contracts_id_attachments_attachmentId_download",
                "tags": [
                    "Portal Contracts"
                ],
                "summary": "Download a contract attachment",
                "description": "GET /api/portal/contracts/{id}/attachments/{attachmentId}/download /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalContractsController@downloadAttachment",
                "x-source": "app/Http/Controllers/Api/Portal/PortalContractsController.php#L100-L113",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "ContractAttachment"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Contract id."
                    },
                    {
                        "name": "attachmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Attachment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/dashboard": {
            "get": {
                "operationId": "get_api_portal_dashboard",
                "tags": [
                    "Portal Dashboard"
                ],
                "summary": "Portal dashboard",
                "description": "GET /api/portal/dashboard - Summary stats for the portal client. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalDashboardController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalDashboardController.php#L17-L69",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "Sale",
                    "Client"
                ],
                "responses": {
                    "200": {
                        "description": "`total_invoices`, `total_amount`, `total_paid`, `sales_due`, `opening_balance`, `total_due`, `recent_invoices[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total_invoices": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total_amount": {
                                            "type": "number"
                                        },
                                        "total_paid": {
                                            "type": "number"
                                        },
                                        "sales_due": {
                                            "type": "number"
                                        },
                                        "opening_balance": {
                                            "type": "number"
                                        },
                                        "total_due": {
                                            "type": "number"
                                        },
                                        "recent_invoices": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "id": {},
                                        "Ref": {},
                                        "date": {},
                                        "GrandTotal": {
                                            "type": "number"
                                        },
                                        "paid_amount": {
                                            "type": "number"
                                        },
                                        "due": {},
                                        "payment_status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/invoices": {
            "get": {
                "operationId": "get_api_portal_invoices",
                "tags": [
                    "Portal Invoices"
                ],
                "summary": "List my invoices",
                "description": "Completed sales of the client, newest first. `search` matches Ref or payment status.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalInvoicesController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalInvoicesController.php#L15-L62",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-paginated": true,
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`invoices[] {id, Ref, date, warehouse_name, GrandTotal, paid_amount, due, payment_status}` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "Ref": {},
                                        "date": {},
                                        "warehouse_name": {},
                                        "GrandTotal": {
                                            "type": "number"
                                        },
                                        "paid_amount": {
                                            "type": "number"
                                        },
                                        "due": {},
                                        "payment_status": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "invoices": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/invoices/{id}": {
            "get": {
                "operationId": "get_api_portal_invoices_id",
                "tags": [
                    "Portal Invoices"
                ],
                "summary": "Get my invoice",
                "description": "Header, totals, `client` and `details[]` with per-line discount and tax.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalInvoicesController@show",
                "x-source": "app/Http/Controllers/Api/Portal/PortalInvoicesController.php#L67-L139",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Invoice object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product_name": {},
                                        "quantity": {
                                            "type": "number"
                                        },
                                        "price": {
                                            "type": "number"
                                        },
                                        "total": {
                                            "type": "number"
                                        },
                                        "DiscountNet": {
                                            "type": "number"
                                        },
                                        "taxe": {
                                            "type": "number"
                                        },
                                        "tax_method": {
                                            "type": "string"
                                        },
                                        "discount_method": {
                                            "type": "string"
                                        },
                                        "id": {},
                                        "Ref": {},
                                        "date": {},
                                        "time": {},
                                        "notes": {},
                                        "GrandTotal": {
                                            "type": "number"
                                        },
                                        "paid_amount": {
                                            "type": "number"
                                        },
                                        "due": {},
                                        "payment_status": {},
                                        "statut": {},
                                        "subtotal": {
                                            "type": "number"
                                        },
                                        "TaxNet": {
                                            "type": "number"
                                        },
                                        "tax_rate": {
                                            "type": "number"
                                        },
                                        "discount": {
                                            "type": "number"
                                        },
                                        "discount_Method": {
                                            "type": "string"
                                        },
                                        "discount_from_points": {
                                            "type": "number"
                                        },
                                        "shipping": {
                                            "type": "number"
                                        },
                                        "client": {
                                            "type": "object",
                                            "properties": {
                                                "name": {},
                                                "email": {},
                                                "phone": {},
                                                "adresse": {}
                                            }
                                        },
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/invoices/{id}/pdf": {
            "get": {
                "operationId": "get_api_portal_invoices_id_pdf",
                "tags": [
                    "Portal Invoices"
                ],
                "summary": "Download my invoice (PDF)",
                "description": "GET /api/portal/invoices/{id}/pdf - Download invoice PDF (client-scoped, secure). /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalInvoicePdfController@download",
                "x-source": "app/Http/Controllers/Api/Portal/PortalInvoicePdfController.php#L22-L127",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "Sale",
                    "Setting",
                    "Unit",
                    "Product",
                    "ProductVariant"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/knowledge-base": {
            "get": {
                "operationId": "get_api_portal_knowledge_base",
                "tags": [
                    "Portal Knowledge Base"
                ],
                "summary": "Knowledge-base articles",
                "description": "GET /api/portal/knowledge-base - list public articles (is_internal=false), grouped. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalKnowledgeBaseController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalKnowledgeBaseController.php#L16-L47",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "KnowledgeBaseArticle",
                    "KnowledgeBaseArticleGroup"
                ],
                "parameters": [
                    {
                        "name": "group_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Group filter."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search title/content."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`groups[]` and `articles[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "groups": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "articles": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/knowledge-base/{slug}": {
            "get": {
                "operationId": "get_api_portal_knowledge_base_slug",
                "tags": [
                    "Portal Knowledge Base"
                ],
                "summary": "Read an article",
                "description": "GET /api/portal/knowledge-base/{slug} - public article by slug. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalKnowledgeBaseController@show",
                "x-source": "app/Http/Controllers/Api/Portal/PortalKnowledgeBaseController.php#L52-L75",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "KnowledgeBaseArticle"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Article slug."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`id`, `title`, `slug`, `content`, `group`, `updated_at`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "title": {},
                                        "slug": {},
                                        "content": {},
                                        "group": {
                                            "type": "object"
                                        },
                                        "updated_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/locale": {
            "get": {
                "operationId": "get_api_portal_locale",
                "tags": [
                    "Portal Language"
                ],
                "summary": "Current locale",
                "description": "GET /api/portal/locale - current locale + supported set (used by the switcher). /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-public": true,
                "x-controller": "Api\\Portal\\PortalLocaleController@show",
                "x-source": "app/Http/Controllers/Api/Portal/PortalLocaleController.php#L43-L49",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "responses": {
                    "200": {
                        "description": "`locale` and `supported` map.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "locale": {},
                                        "supported": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "post_api_portal_locale",
                "tags": [
                    "Portal Language"
                ],
                "summary": "Set locale",
                "description": "Session + cookie; also saved on the signed-in client.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-public": true,
                "x-controller": "Api\\Portal\\PortalLocaleController@update",
                "x-source": "app/Http/Controllers/Api/Portal/PortalLocaleController.php#L57-L76",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "locale": {
                                        "type": "string",
                                        "x-enum-source": "array_keys(\\App\\Http\\Middleware\\SetLocale::SUPPORTED)",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "in:array_keys(\\App\\Http\\Middleware\\SetLocale::SUPPORTED)"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Supported locale code."
                                    }
                                },
                                "required": [
                                    "locale"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `locale`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "locale": {}
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/api/portal/login": {
            "post": {
                "operationId": "post_api_portal_login",
                "tags": [
                    "Portal Authentication"
                ],
                "summary": "Portal login",
                "description": "Starts a portal session. Disabled accounts get `403`.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-public": true,
                "x-controller": "Api\\Portal\\PortalAuthController@login",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAuthController.php#L21-L51",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "PortalClient"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Portal email."
                                    },
                                    "password": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Password."
                                    },
                                    "remember": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remember me.",
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "email",
                                    "password"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `portal_client` (with linked client).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "portal_client": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid credentials.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Account disabled.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/api/portal/logout": {
            "post": {
                "operationId": "post_api_portal_logout",
                "tags": [
                    "Portal Authentication"
                ],
                "summary": "Portal logout",
                "description": "Clears only the portal guard; other guards in the same session are untouched.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalAuthController@logout",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAuthController.php#L56-L62",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/me": {
            "get": {
                "operationId": "get_api_portal_me",
                "tags": [
                    "Portal Authentication"
                ],
                "summary": "Current portal client",
                "description": "GET /api/portal/me - Current authenticated portal client (for session check). /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalAuthController@me",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAuthController.php#L67-L87",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "responses": {
                    "200": {
                        "description": "`portal_client`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "portal_client": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Account disabled (session cleared).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/payments": {
            "get": {
                "operationId": "get_api_portal_payments",
                "tags": [
                    "Portal Payments"
                ],
                "summary": "List my payments",
                "description": "Sale payments of the client with method, newest first. `search` matches Ref, date or method.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalPaymentsController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalPaymentsController.php#L16-L97",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "payments": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/profile": {
            "delete": {
                "operationId": "delete_api_portal_profile",
                "tags": [
                    "Portal Profile"
                ],
                "summary": "Close my portal account",
                "description": "Deletes the portal login only (client and accounting records remain). Refused while the account owes money.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalProfileController@destroyAccount",
                "x-source": "app/Http/Controllers/Api/Portal/PortalProfileController.php#L77-L130",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "PortalAccountDeletion",
                    "PortalClient"
                ],
                "parameters": [
                    {
                        "name": "confirm_email",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "x-laravel-rules": [
                                "required",
                                "string"
                            ],
                            "x-sources": [
                                "validated"
                            ]
                        },
                        "description": "Type the account email to confirm."
                    },
                    {
                        "name": "current_password",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "x-laravel-rules": [
                                "required",
                                "string"
                            ],
                            "x-sources": [
                                "validated"
                            ]
                        },
                        "description": "Current password."
                    },
                    {
                        "name": "reason",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 500,
                            "nullable": true,
                            "x-laravel-rules": [
                                "nullable",
                                "string",
                                "max:500"
                            ],
                            "x-sources": [
                                "validated"
                            ]
                        },
                        "description": "Optional reason."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "409": {
                        "description": "Outstanding balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        },
                                        "outstanding": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_portal_profile",
                "tags": [
                    "Portal Profile"
                ],
                "summary": "My profile",
                "description": "GET /api/portal/profile - Profile info (client + portal email). /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalProfileController@show",
                "x-source": "app/Http/Controllers/Api/Portal/PortalProfileController.php#L20-L42",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "responses": {
                    "200": {
                        "description": "`portal_email`, `preferred_locale`, `client {…}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "portal_email": {},
                                        "preferred_locale": {},
                                        "client": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "name": {},
                                                "email": {},
                                                "phone": {},
                                                "adresse": {},
                                                "country": {},
                                                "city": {},
                                                "state": {},
                                                "zip": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/profile/password": {
            "put": {
                "operationId": "put_api_portal_profile_password",
                "tags": [
                    "Portal Profile"
                ],
                "summary": "Change my password",
                "description": "PUT /api/portal/profile/password - Update portal password. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalProfileController@updatePassword",
                "x-source": "app/Http/Controllers/Api/Portal/PortalProfileController.php#L47-L64",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "current_password": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Current password."
                                    },
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "confirmed (send <field>_confirmation)",
                                            "defaults"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "confirmed",
                                            "defaults"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "New password."
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "description": "Repeat the new password.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "current_password",
                                    "password",
                                    "password_confirmation"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/quotations": {
            "get": {
                "operationId": "get_api_portal_quotations",
                "tags": [
                    "Portal Quotations"
                ],
                "summary": "List my quotations",
                "description": "GET /api/portal/quotations - list quotations belonging to the authenticated client. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalQuotationsController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalQuotationsController.php#L19-L62",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-paginated": true,
                "x-models": [
                    "Quotation"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`quotations[] {id, Ref, date, warehouse_name, GrandTotal, statut, notes}` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "Ref": {},
                                        "date": {},
                                        "warehouse_name": {},
                                        "GrandTotal": {
                                            "type": "number"
                                        },
                                        "statut": {},
                                        "notes": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "quotations": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_portal_quotations",
                "tags": [
                    "Portal Quotations"
                ],
                "summary": "Request a quotation",
                "description": "Creates a `pending` quotation with free-text lines for staff to price.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalQuotationsController@store",
                "x-source": "app/Http/Controllers/Api/Portal/PortalQuotationsController.php#L105-L172",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "Setting",
                    "Warehouse",
                    "User",
                    "Quotation"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "description": {
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "x-conditional": [
                                                        "required_with:items"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:items",
                                                        "string",
                                                        "max:255"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Item description."
                                                },
                                                "quantity": {
                                                    "type": "number",
                                                    "minimum": 0.0001,
                                                    "x-conditional": [
                                                        "required_with:items"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:items",
                                                        "numeric",
                                                        "min:0.0001"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Requested lines."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "maxLength": 5000,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:5000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Request details."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Subject."
                                    }
                                },
                                "required": [
                                    "notes"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success`, `id`, `Ref`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "Ref": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/quotations/{id}": {
            "get": {
                "operationId": "get_api_portal_quotations_id",
                "tags": [
                    "Portal Quotations"
                ],
                "summary": "Get my quotation",
                "description": "GET /api/portal/quotations/{id} - quotation detail (must belong to client). /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalQuotationsController@show",
                "x-source": "app/Http/Controllers/Api/Portal/PortalQuotationsController.php#L67-L99",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "Quotation"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Quotation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Quotation with `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "Ref": {},
                                        "date": {},
                                        "warehouse_name": {},
                                        "GrandTotal": {
                                            "type": "number"
                                        },
                                        "discount": {
                                            "type": "number"
                                        },
                                        "shipping": {
                                            "type": "number"
                                        },
                                        "TaxNet": {
                                            "type": "number"
                                        },
                                        "tax_rate": {
                                            "type": "number"
                                        },
                                        "statut": {},
                                        "notes": {},
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "product_name": {},
                                        "quantity": {
                                            "type": "number"
                                        },
                                        "price": {
                                            "type": "number"
                                        },
                                        "total": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/set-password": {
            "post": {
                "operationId": "post_api_portal_set_password",
                "tags": [
                    "Portal Authentication"
                ],
                "summary": "Accept invitation / set password",
                "description": "Sets the password, activates the account, clears the token and signs the client in.",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-public": true,
                "x-controller": "Api\\Portal\\PortalAuthController@setPassword",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAuthController.php#L115-L144",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "PortalClient"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "confirmed (send <field>_confirmation)",
                                            "defaults"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "confirmed",
                                            "defaults"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "New password."
                                    },
                                    "token": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Invitation token."
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "description": "Repeat the password.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "password",
                                    "token",
                                    "password_confirmation"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `portal_client`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "portal_client": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid or expired token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/api/portal/statement": {
            "get": {
                "operationId": "get_api_portal_statement",
                "tags": [
                    "Portal Statement"
                ],
                "summary": "My account statement",
                "description": "GET /api/portal/statement - Account statement (ledger) for the authenticated client. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-controller": "Api\\Portal\\PortalStatementController@index",
                "x-source": "app/Http/Controllers/Api/Portal/PortalStatementController.php#L17-L180",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1",
                    "auth:portal"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "Client",
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "from_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "to_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`client`, `opening_balance`, `current_opening_balance`, `entries[]` (invoices and payments with running balance), `closing_balance`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "client": {
                                            "type": "object",
                                            "properties": {
                                                "name": {},
                                                "email": {},
                                                "opening_balance": {}
                                            }
                                        },
                                        "opening_balance": {},
                                        "current_opening_balance": {},
                                        "entries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "closing_balance": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "PortalSession": []
                    }
                ]
            }
        },
        "/api/portal/translations/{locale}": {
            "get": {
                "operationId": "get_api_portal_translations_locale",
                "tags": [
                    "Portal Language"
                ],
                "summary": "Portal translation bundle",
                "description": "GET /api/portal/translations/{locale} - the whole resources/lang/{locale}/portal.php as a flat JSON map, exactly what vue-i18n consumes. /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-public": true,
                "x-controller": "Api\\Portal\\PortalLocaleController@translations",
                "x-source": "app/Http/Controllers/Api/Portal/PortalLocaleController.php#L28-L38",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "parameters": [
                    {
                        "name": "locale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "en"
                        },
                        "description": "Locale code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Flat key → text map.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/portal/validate-invite": {
            "get": {
                "operationId": "get_api_portal_validate_invite",
                "tags": [
                    "Portal Authentication"
                ],
                "summary": "Validate an invitation token",
                "description": "GET /api/portal/accept-invite - Validate invitation token (for set-password page). /",
                "x-section": "Client Portal",
                "x-surface": "portal",
                "x-public": true,
                "x-controller": "Api\\Portal\\PortalAuthController@validateInviteToken",
                "x-source": "app/Http/Controllers/Api/Portal/PortalAuthController.php#L92-L110",
                "x-middleware": [
                    "web",
                    "portal.locale",
                    "portal.auth",
                    "throttle:60,1"
                ],
                "x-rate-limit": {
                    "requests": 60,
                    "per_minutes": 1
                },
                "x-models": [
                    "PortalClient"
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Invitation token from the email."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`valid: true` and `email`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "valid": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "email": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid or expired (48 h).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "valid": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/pos/create_draft": {
            "post": {
                "operationId": "post_api_pos_create_draft",
                "tags": [
                    "POS"
                ],
                "summary": "Hold a cart as a draft sale",
                "description": "Saves the current cart as a **draft** (no stock movement, no payments) so it can be resumed later. With `draft_sale_id` the existing draft's header and lines are replaced; otherwise a new draft with its own `Ref` is created.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@CreateDraft",
                "x-source": "app/Http/Controllers/PosController.php#L1026-L1140",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "DraftSale",
                    "DraftSaleDetail"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cart lines (same structure as POS sale lines).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "discount_Method": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1`/`2`."
                                    },
                                    "draft_sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Existing draft to update."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos/create_pos": {
            "post": {
                "operationId": "post_api_pos_create_pos",
                "tags": [
                    "POS"
                ],
                "summary": "Submit a POS sale",
                "description": "Creates a **completed** POS sale from the cart and its payments in one transaction:\n\n- validates warehouse access, pack stock and, for multiple payment lines, that the total paid does not exceed `GrandTotal` (`422` with `change_return`);\n- **wallet** tender: the customer's store-wallet balance is checked and debited;\n- stock, batches and serials are consumed; loyalty points are earned, and `used_points` redeemed;\n- promotions: `promotion_code` and the `promotion_*` cart context are re-evaluated server-side and recorded as usages;\n- one `payment_sales` row per payment line (account balances credited); card lines may carry Stripe tokens (`token`, `card_tokens_by_line`);\n- `kitchen_action` sends the ticket to the kitchen display (`send`) when the module is on;\n- `send_email` / `send_sms` trigger the receipt notifications;\n- when `draft_sale_id` is given the held draft is deleted.\n\n`sale_uuid` is an idempotency key: resubmitting the same UUID returns the existing sale id without touching stock or payments. Response includes `updated_stock` rows for the grid and `server_time`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@CreatePOS",
                "x-source": "app/Http/Controllers/PosController.php#L117-L755",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Sale",
                    "PromotionUsage",
                    "Product",
                    "Unit",
                    "SaleDetail",
                    "product_warehouse",
                    "Client",
                    "PaymentWithCreditCard",
                    "PaymentSale",
                    "Account",
                    "DraftSale",
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ticket total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "card_tokens_by_line": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON object mapping payment line index → Stripe token.",
                                        "type": "object"
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cart lines (same structure as sales: `product_id, product_variant_id, quantity, sale_unit_id, Unit_price, tax_percent, tax_method, discount, discount_Method, subtotal, imei_number, batches, product_pack_id, pack_multiplier, pack_name, price_type`).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "discount_Method": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1` percent / `2` fixed."
                                    },
                                    "discount_from_points": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount amount from points."
                                    },
                                    "draft_sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Draft to delete after submitting."
                                    },
                                    "kitchen_action": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`send` to push the ticket to the kitchen display."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ticket notes."
                                    },
                                    "payment_note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Note stored on the payment rows."
                                    },
                                    "payments": {
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Payment lines, at least one: `[{amount, payment_method_id, account_id?, change?}]`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "promotion_code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Promotion code entered."
                                    },
                                    "promotion_item_count": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Item count for promotion evaluation."
                                    },
                                    "promotion_product_ids": {
                                        "x-inferred": true,
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        },
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Product ids in the cart."
                                    },
                                    "promotion_product_subtotals": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Per-product subtotals `[{product_id, subtotal}]`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "promotion_subtotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cart subtotal used for promotion evaluation."
                                    },
                                    "sale_uuid": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Client-generated idempotency key."
                                    },
                                    "seller_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Salesperson user id (salesperson switch)."
                                    },
                                    "send_email": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` to email the receipt.",
                                        "type": "boolean"
                                    },
                                    "send_sms": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` to SMS the receipt.",
                                        "type": "boolean"
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping cost.",
                                        "type": "number"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Stripe card token for a single card payment."
                                    },
                                    "used_points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty points redeemed.",
                                        "type": "number"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "payments",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "client_id": 1,
                                "warehouse_id": 1,
                                "GrandTotal": 39.8,
                                "tax_rate": 0,
                                "TaxNet": 0,
                                "discount": 0,
                                "discount_Method": "2",
                                "shipping": 0,
                                "sale_uuid": "b6d1c1a2-5f3e-4d1c-9a0e-1b2c3d4e5f60",
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 2,
                                        "sale_unit_id": 1,
                                        "Unit_price": 19.9,
                                        "tax_percent": 0,
                                        "tax_method": "1",
                                        "discount": 0,
                                        "discount_Method": "2",
                                        "subtotal": 39.8,
                                        "imei_number": null
                                    }
                                ],
                                "payments": [
                                    {
                                        "amount": 39.8,
                                        "payment_method_id": 1,
                                        "account_id": 1
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, sale `id`, `qbo_sync`, `updated_stock[]`, `server_time`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "qbo_sync": {},
                                        "updated_stock": {},
                                        "server_time": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "id": 42,
                                    "qbo_sync": null,
                                    "updated_stock": [
                                        {
                                            "id": 5,
                                            "product_variant_id": null,
                                            "qte_sale": 48
                                        }
                                    ],
                                    "server_time": "2026-09-06T10:15:00+00:00"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos/customer-display/broadcast": {
            "post": {
                "operationId": "post_api_pos_customer_display_broadcast",
                "tags": [
                    "Customer Display"
                ],
                "summary": "Broadcast the cart to the customer display",
                "description": "**Public.** Called by the POS on every cart change: normalises the cart to a safe shape (`currency, discount, TaxNet, shipping, GrandTotal, details[] {name, quantity, Net_price, unit_price, line_total, subtotal}`), caches it for 2 minutes under `screen_id` and fires the `CartUpdated` broadcast event. `completed: true` tells the display to show the thank-you screen.",
                "x-section": "Point of Sale",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\CustomerDisplayController@broadcastCart",
                "x-source": "app/Http/Controllers/Api/CustomerDisplayController.php#L46-L81",
                "x-middleware": [
                    "api"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "cart": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cart object with `details[]` (or `items[]`), totals and `currency`.",
                                        "type": "object"
                                    },
                                    "completed": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` when the ticket was just paid.",
                                        "type": "boolean"
                                    },
                                    "screen_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Display number (default `1`).",
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "quantity": {
                                            "type": "number"
                                        },
                                        "Net_price": {
                                            "type": "number"
                                        },
                                        "unit_price": {
                                            "type": "number"
                                        },
                                        "line_total": {
                                            "type": "number"
                                        },
                                        "subtotal": {
                                            "type": "number"
                                        },
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/pos/customer-display/last-cart": {
            "get": {
                "operationId": "get_api_pos_customer_display_last_cart",
                "tags": [
                    "Customer Display"
                ],
                "summary": "Poll the last broadcast cart",
                "description": "**Public.** Fallback for displays without WebSockets: returns the cached `cart`, `completed` flag and `ts` for `screen`, or `cart: null` when nothing was broadcast in the last 2 minutes.",
                "x-section": "Point of Sale",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\CustomerDisplayController@lastCart",
                "x-source": "app/Http/Controllers/Api/CustomerDisplayController.php#L84-L93",
                "x-middleware": [
                    "api"
                ],
                "parameters": [
                    {
                        "name": "screen",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Display number (default `1`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`cart`, `completed`, `ts`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "cart": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "completed": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/pos/data_create_pos": {
            "get": {
                "operationId": "get_api_pos_data_create_pos",
                "tags": [
                    "POS"
                ],
                "summary": "Get POS boot data",
                "description": "Everything the POS screen needs at start-up: `setting` (global settings incl. `allow_overselling`), `pos_settings` (receipt / layout options), `stripe_key`, `clients` (`id, name, phone`), `defaultClient` / `default_client_name` / `default_client_points` / `default_client_eligible`, the caller's `warehouses` and `defaultWarehouse`, `categories`, `brands`, `accounts`, `payment_methods`, `languages_available`, `products_per_page`, `point_to_amount_rate`, `default_tax`, `default_account_id`, `default_payment_method_id`, and salesperson-switch settings (`enable_pos_salesperson_switch`, `salespeople`).",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@GetELementPos",
                "x-source": "app/Http/Controllers/PosController.php#L2205-L2339",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Setting",
                    "Account",
                    "Warehouse",
                    "UserWarehouse",
                    "Category",
                    "Brand",
                    "PosSetting",
                    "User",
                    "PaymentMethod",
                    "Language"
                ],
                "responses": {
                    "200": {
                        "description": "POS boot payload.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "setting": {
                                            "type": "object",
                                            "properties": {
                                                "logo": {},
                                                "CompanyName": {},
                                                "CompanyAdress": {},
                                                "email": {},
                                                "CompanyPhone": {},
                                                "vat_number": {},
                                                "company_name_ar": {},
                                                "zatca_enabled": {
                                                    "type": "boolean"
                                                },
                                                "invoice_format": {},
                                                "offline_sync_enabled": {
                                                    "type": "boolean"
                                                }
                                            }
                                        },
                                        "stripe_key": {},
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "defaultWarehouse": {},
                                        "defaultClient": {},
                                        "default_client_name": {
                                            "type": "string"
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "languages_available": {},
                                        "products_per_page": {
                                            "type": "integer"
                                        },
                                        "default_client_points": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "default_client_eligible": {},
                                        "point_to_amount_rate": {},
                                        "default_tax": {},
                                        "default_account_id": {},
                                        "default_payment_method_id": {},
                                        "pos_settings": {},
                                        "enable_pos_salesperson_switch": {
                                            "type": "boolean"
                                        },
                                        "salespeople": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos/data_draft_convert_sale/{id}": {
            "get": {
                "operationId": "get_api_pos_data_draft_convert_sale_id",
                "tags": [
                    "POS"
                ],
                "summary": "Resume a draft in the POS",
                "description": "Loads a draft in POS-cart shape: `sale` header (`client_id, warehouse_id, tax_rate, TaxNet, discount, discount_Method, shipping, currency_id, exchange_rate`), `GrandTotal`, `details[]` lines with current stock and pack options, plus the same lookups as the POS boot data and the customer's loyalty info.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@data_draft_convert_sale",
                "x-source": "app/Http/Controllers/PosController.php#L1545-L1774",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Setting",
                    "Account",
                    "DraftSale",
                    "Warehouse",
                    "UserWarehouse",
                    "ProductPack",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant",
                    "Category",
                    "Brand",
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Draft sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Draft in cart shape with lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stripe_key": {},
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouse_id": {},
                                        "client_id": {},
                                        "client_name": {
                                            "type": "string"
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale": {},
                                        "GrandTotal": {
                                            "type": "integer"
                                        },
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "defaultClient": {},
                                        "default_client_points": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "default_client_eligible": {},
                                        "point_to_amount_rate": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos/get_products_pos": {
            "get": {
                "operationId": "get_api_pos_get_products_pos",
                "tags": [
                    "POS"
                ],
                "summary": "Load the POS product grid",
                "description": "Products sellable in `warehouse_id` (one row per product or variant): `id, product_variant_id, code, barcode, name, Variant, image, product_type, unit, Unit_price, Net_price, wholesale_price, min_price, tax_method, tax_percent, discount_method, discount, qte_sale, stock_alert, is_imei, is_batch_tracked, packs[], wholesale_tiers[], promo_*, fitment flags`. Products marked *not for selling* are excluded; zero-stock rows are included when overselling is allowed. `server_time` is returned so the client can ask for deltas later.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@GetProductsByParametre",
                "x-source": "app/Http/Controllers/PosController.php#L1791-L2122",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "product_warehouse",
                    "ProductPack",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "brand_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this brand."
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this category."
                    },
                    {
                        "name": "product_combo",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = include combo products."
                    },
                    {
                        "name": "product_service",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = include services."
                    },
                    {
                        "name": "stock",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = only products with stock (unless overselling allowed)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse to load (must be assigned to the cashier)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`products[]`, `totalRows`, `server_time`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "server_time": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos/get_products_pos_changes": {
            "get": {
                "operationId": "get_api_pos_get_products_pos_changes",
                "tags": [
                    "POS"
                ],
                "summary": "Get stock changes since a timestamp",
                "description": "Incremental refresh for the POS grid: returns the rows of `warehouse_id` whose stock changed after `since` (ISO 8601, use the previous `server_time`). Without `since` the whole warehouse is returned.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@GetProductsChanges",
                "x-source": "app/Http/Controllers/PosController.php#L2129-L2172",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "ISO 8601 timestamp of the last sync."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`products[]` (changed rows) and `server_time`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "server_time": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos/submit_sale_from_draft": {
            "post": {
                "operationId": "post_api_pos_submit_sale_from_draft",
                "tags": [
                    "POS"
                ],
                "summary": "Submit a draft as a sale (legacy single payment)",
                "description": "Turns a held draft into a **completed** POS sale using the legacy single-payment payload (`payment.amount`, `payment.payment_method_id`, `payment.account_id`, `amount`, `change`). Stock, batches, points and payment are applied like *Submit a POS sale*; the draft is deleted afterwards. Prefer `POST /api/pos/create_pos` with `draft_sale_id` for split payments.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@submit_sale_from_draft",
                "x-source": "app/Http/Controllers/PosController.php#L1167-L1541",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "DraftSale",
                    "Sale",
                    "Product",
                    "Unit",
                    "SaleDetail",
                    "product_warehouse",
                    "Client",
                    "PaymentWithCreditCard",
                    "PaymentSale",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount paid (legacy duplicate)."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Change returned.",
                                        "type": "number"
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cart lines.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "discount_Method": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1`/`2`."
                                    },
                                    "discount_from_points": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Points discount."
                                    },
                                    "draft_sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Draft to convert."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment": {
                                        "x-inferred": true,
                                        "type": "object",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Payment object `{amount, payment_method_id, account_id}`.",
                                        "properties": {
                                            "amount": {
                                                "x-inferred": true,
                                                "type": "number",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount paid. Required."
                                            }
                                        },
                                        "required": [
                                            "amount"
                                        ]
                                    },
                                    "seller_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Salesperson id."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Stripe token for card payments."
                                    },
                                    "used_points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Points redeemed.",
                                        "type": "number"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, sale `id`, `qbo_sync`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "qbo_sync": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "500": {
                        "description": "Payment gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos/wallet-balance/{client}": {
            "get": {
                "operationId": "get_api_pos_wallet_balance_client",
                "tags": [
                    "POS"
                ],
                "summary": "Get a customer's wallet balance",
                "description": "Current store-wallet `balance` of the customer and whether the wallet tender is `enabled`, for the *Pay with wallet* button.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@walletBalance",
                "x-source": "app/Http/Controllers/PosController.php#L105-L115",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Wallet",
                    "StoreSetting"
                ],
                "parameters": [
                    {
                        "name": "client",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`balance` and `enabled`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "balance": {
                                            "type": "number"
                                        },
                                        "enabled": {
                                            "type": "boolean"
                                        }
                                    }
                                },
                                "example": {
                                    "balance": 25.5,
                                    "enabled": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/pos_settings/{id}": {
            "put": {
                "operationId": "put_api_pos_settings_id",
                "tags": [
                    "System Settings"
                ],
                "summary": "Update POS settings",
                "description": "Partial update of the POS behaviour, receipt layout, printer and label-printer configuration. Only keys present in the payload are written. `invoice_format` is persisted on the global settings row. `label_printer_connection` is coerced to `windows` unless it is `network` or `qz`; `label_printer_render_mode` is `native` unless it is `raster`.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@update_pos_settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L461-L784",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "pos_settings",
                        "slug": "pos_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "PosSetting",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "ID of the `pos_settings` row (always `1`)."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "allow_overselling": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow sales to push stock negative. Stored on the global settings row (mirrors the feature toggle)."
                                    },
                                    "barcode_scanning_sound": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Play a beep on successful scan.",
                                        "type": "boolean"
                                    },
                                    "cash_drawer_auto_open": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Open the cash drawer after each sale.",
                                        "type": "boolean"
                                    },
                                    "cash_drawer_printer_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "QZ printer name that drives the drawer kick."
                                    },
                                    "direct_network_printing": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Send receipts straight to a network ESC/POS printer instead of the browser dialog.",
                                        "type": "boolean"
                                    },
                                    "enable_customer_points": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show and redeem loyalty points in POS."
                                    },
                                    "enable_hold_sales": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow parking/holding sales."
                                    },
                                    "invoice_format": {
                                        "type": "string",
                                        "enum": [
                                            "thermal",
                                            "a4"
                                        ],
                                        "description": "Global invoice layout.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "is_printable": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the receipt automatically after checkout."
                                    },
                                    "label_printer_connection": {
                                        "type": "string",
                                        "enum": [
                                            "windows",
                                            "network",
                                            "qz"
                                        ],
                                        "description": "Label printer transport.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "label_printer_density": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "TSPL darkness 0–15.",
                                        "type": "integer"
                                    },
                                    "label_printer_direction": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "TSPL DIRECTION (0 or 1).",
                                        "type": "integer"
                                    },
                                    "label_printer_dpi": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Printhead resolution (203 or 300).",
                                        "type": "integer"
                                    },
                                    "label_printer_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable direct label printing."
                                    },
                                    "label_printer_gap_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Gap between labels in mm.",
                                        "type": "number"
                                    },
                                    "label_printer_height_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Label height in mm.",
                                        "type": "number"
                                    },
                                    "label_printer_ip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Label printer IP (network mode)."
                                    },
                                    "label_printer_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Printer name as reported by QZ Tray."
                                    },
                                    "label_printer_offset_x_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Horizontal print offset in mm.",
                                        "type": "number"
                                    },
                                    "label_printer_offset_y_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Vertical print offset in mm.",
                                        "type": "number"
                                    },
                                    "label_printer_port": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Label printer port (network mode).",
                                        "type": "integer"
                                    },
                                    "label_printer_render_mode": {
                                        "type": "string",
                                        "enum": [
                                            "native",
                                            "raster"
                                        ],
                                        "description": "Label rendering mode.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "label_printer_speed": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print speed (in/s).",
                                        "type": "integer"
                                    },
                                    "label_printer_tear": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tear-off mode on/off.",
                                        "type": "boolean"
                                    },
                                    "label_printer_width_mm": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Label width in mm.",
                                        "type": "number"
                                    },
                                    "logo_size": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Logo size on receipts."
                                    },
                                    "network_printer_ip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Receipt printer IP."
                                    },
                                    "network_printer_port": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Receipt printer port (usually 9100).",
                                        "type": "integer"
                                    },
                                    "note_customer": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default note printed for the customer on receipts."
                                    },
                                    "products_per_page": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Number of product tiles per page in POS.",
                                        "type": "integer"
                                    },
                                    "quick_add_customer": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the quick-add-customer button in POS.",
                                        "type": "boolean"
                                    },
                                    "receipt_font_family": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Receipt font family."
                                    },
                                    "receipt_font_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Receipt font size in px.",
                                        "type": "integer"
                                    },
                                    "receipt_layout": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Receipt template variant."
                                    },
                                    "receipt_paper_size": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Receipt paper width (e.g. `80mm`, `58mm`)."
                                    },
                                    "show_Warehouse": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the warehouse name."
                                    },
                                    "show_address": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the company address."
                                    },
                                    "show_barcode": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the sale barcode."
                                    },
                                    "show_brands": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the brand filter bar."
                                    },
                                    "show_categories": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the category filter bar."
                                    },
                                    "show_customer": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the customer name."
                                    },
                                    "show_date": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the date."
                                    },
                                    "show_discount": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the order discount line."
                                    },
                                    "show_due": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the due amount."
                                    },
                                    "show_email": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the company email."
                                    },
                                    "show_items_tax": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print per-line tax."
                                    },
                                    "show_logo": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the logo on receipts."
                                    },
                                    "show_net_balance": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the net balance."
                                    },
                                    "show_note": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the note."
                                    },
                                    "show_paid": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the paid amount."
                                    },
                                    "show_payments": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the payment breakdown."
                                    },
                                    "show_phone": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the company phone."
                                    },
                                    "show_previous_dues": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the customer's previous balance."
                                    },
                                    "show_product_discount": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print per-line discounts."
                                    },
                                    "show_product_images": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show product images on tiles."
                                    },
                                    "show_reference": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the reference number."
                                    },
                                    "show_seller": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the salesperson."
                                    },
                                    "show_shipping": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print shipping."
                                    },
                                    "show_stock_quantity": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show stock badge on tiles.",
                                        "type": "boolean"
                                    },
                                    "show_store_name": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the store name."
                                    },
                                    "show_tax": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the order tax line."
                                    },
                                    "show_zatca_qr": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Print the ZATCA QR code."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/logs": {
            "delete": {
                "operationId": "delete_api_prestashop_logs",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Clear PrestaShop logs",
                "description": "Clears the PrestaShop sync log.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@clearLogs",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L169-L176",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "x-models": [
                    "PrestashopLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_prestashop_logs",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "PrestaShop logs",
                "description": "Paginated PrestaShop sync log entries.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@logs",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L157-L167",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PrestashopLog"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Level."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/reset-mappings": {
            "post": {
                "operationId": "post_api_prestashop_reset_mappings",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Reset PrestaShop mappings",
                "description": "Deletes all product/category ID mappings so the next sync re-matches items by reference.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@resetMappings",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L98-L107",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entity_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "product",
                                            "customer",
                                            "order"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:product,customer,order"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`product`, `customer`, `order` (omit for all)."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `deleted`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "deleted": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/settings": {
            "get": {
                "operationId": "get_api_prestashop_settings",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Get PrestaShop settings",
                "description": "Current PrestaShop settings (store URL, webservice key masked, default warehouse, sync options).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@settings",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L20-L36",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "x-models": [
                    "PrestashopSetting",
                    "Warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `configured`, `store_url`, `has_api_key`, `default_language_id`, `warehouse_id`, `warehouses[]`, `last_sync_at`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "configured": {},
                                        "store_url": {},
                                        "has_api_key": {},
                                        "default_language_id": {
                                            "type": "integer"
                                        },
                                        "warehouse_id": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "last_sync_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_prestashop_settings",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Save PrestaShop settings",
                "description": "Saves the store URL, webservice key, default warehouse/customer and sync options.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@saveSettings",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L38-L68",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "x-models": [
                    "PrestashopSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "api_key": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Webservice key (write-only)."
                                    },
                                    "default_language_id": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "PrestaShop language id for names."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "store_url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191",
                                            "url"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Shop URL."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse used for stock and imported orders."
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `configured`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "configured": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/stats": {
            "get": {
                "operationId": "get_api_prestashop_stats",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Sync statistics",
                "description": "Counters: mapped products, orders imported, last sync times.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@stats",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L91-L96",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Mapped counts.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/sync/inventory": {
            "post": {
                "operationId": "post_api_prestashop_sync_inventory",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Push stock levels",
                "description": "Pushes current stock quantities of mapped products to PrestaShop.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@syncInventory",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L127-L139",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call (default 25).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `pushed`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/sync/orders": {
            "post": {
                "operationId": "post_api_prestashop_sync_orders",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Pull orders into sales",
                "description": "Imports new PrestaShop orders as sales; already imported orders are skipped.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@syncOrders",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L141-L155",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "page_info": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Page number.",
                                        "type": "integer"
                                    },
                                    "per_page": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Page size (default 25).",
                                        "type": "integer"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse for the sales."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `imported`, `skipped`, `next_page`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/sync/products": {
            "post": {
                "operationId": "post_api_prestashop_sync_products",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Push or pull products",
                "description": "`mode=push` (default) sends Stocky products in batches; `mode=pull` imports PrestaShop products page by page.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@syncProducts",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L109-L125",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push: rows per call (default 15).",
                                        "type": "integer"
                                    },
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`push` or `pull`."
                                    },
                                    "page_info": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pull: page number.",
                                        "type": "integer"
                                    },
                                    "per_page": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pull: page size (default 50).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push: resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Result with counts and `done` / `next_page`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/prestashop/test-connection": {
            "post": {
                "operationId": "post_api_prestashop_test_connection",
                "tags": [
                    "PrestaShop"
                ],
                "summary": "Test the PrestaShop connection",
                "description": "Calls the PrestaShop webservice with the stored key and reports success or the error.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\PrestashopSyncController@testConnection",
                "x-source": "app/Http/Controllers/Integrations/PrestashopSyncController.php#L70-L89",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "PrestashopSettingPolicy"
                    }
                ],
                "x-models": [
                    "PrestashopSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not configured / failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Add the store URL and webservice key first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/preview_import_purchases": {
            "post": {
                "operationId": "post_api_preview_import_purchases",
                "tags": [
                    "Purchases"
                ],
                "summary": "Preview a purchase CSV import",
                "description": "Parses a CSV (`productcode`, `qty`) and returns the resolved rows (`code, name, qty, cost, total, unit, is_batch_tracked, product_id`) with the `subtotal`, without saving. Unknown codes are skipped.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@preview_import_purchases",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2155-L2209",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchases_add",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "CSV file."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`rows[]`, `subtotal`, `count` — or `status: false` with `msg`/`errors` when the file is invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "msg": {
                                            "type": "string",
                                            "example": "Invalid CSV file"
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "errors": {},
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "subtotal": {
                                            "type": "integer"
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/preview_import_sales": {
            "post": {
                "operationId": "post_api_preview_import_sales",
                "tags": [
                    "Sales"
                ],
                "summary": "Preview a sale CSV import",
                "description": "Parses a CSV of lines (`productcode`, `qty`, optional `price`, `unit_sale_id`, `product_variant_id`) and returns the resolved rows with product names, units and totals without saving anything.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@preview_import_sales",
                "x-source": "app/Http/Controllers/SalesController.php#L2328-L2397",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "Unit"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "CSV file."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`rows[]`, `grand_total`, `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "grand_total": {},
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "File could not be read or invalid rows (`errors`, `details`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "msg": {
                                            "type": "string",
                                            "example": "Could not read file."
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "errors": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/print_labels_direct": {
            "post": {
                "operationId": "post_api_print_labels_direct",
                "tags": [
                    "Products"
                ],
                "summary": "Print barcode labels on a TSPL label printer",
                "description": "Sends labels straight to the configured thermal label printer (TSPL). Two render modes, chosen by POS settings:\n\n- **native** – send `labels[]` (`barcode`, `name`, `Net_price`, `Type_barcode`, `qte` copies) and the printer draws text and barcodes.\n- **raster** – send `rasters[]` (`data` base64 1-bit bitmap, `width_bytes`, `height`, `qte`) rendered by the browser at 203 dpi so the print matches the preview.\n\n`design` carries the label layout; the configured sticker size overrides its `width_mm`/`height_mm`. When the printer is reached through QZ Tray (client-side), the TSPL bytes are returned as `payload_base64` for the browser to deliver instead of being sent by the server.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@Print_Labels_Direct",
                "x-source": "app/Http/Controllers/ProductsController.php#L2712-L2786",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "barcode",
                        "slug": "barcode_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "PosSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "design": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Label design object from the barcode page (fields, font sizes, sticker size)."
                                    },
                                    "labels": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "Net_price": {
                                                    "x-inferred": true,
                                                    "type": "number",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Price line."
                                                },
                                                "Type_barcode": {
                                                    "type": "string",
                                                    "maxLength": 20,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:20"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Symbology, max 20 chars."
                                                },
                                                "barcode": {
                                                    "type": "string",
                                                    "maxLength": 64,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:64"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Barcode value."
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:255"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product name line."
                                                },
                                                "qte": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "maximum": 1000,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer",
                                                        "min:1",
                                                        "max:1000"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Copies of this label, 1–1000."
                                                }
                                            }
                                        },
                                        "minItems": 1,
                                        "maxItems": 200,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1",
                                            "max:200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Native mode: array of labels, 1–200 items."
                                    },
                                    "rasters": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "string",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "string"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Base64-encoded 1-bit bitmap rows."
                                                },
                                                "height": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer",
                                                        "min:1"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Height in dots."
                                                },
                                                "qte": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "maximum": 1000,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer",
                                                        "min:1",
                                                        "max:1000"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Copies, 1–1000."
                                                },
                                                "width_bytes": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer",
                                                        "min:1"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Row width in bytes."
                                                }
                                            },
                                            "required": [
                                                "data",
                                                "height",
                                                "width_bytes"
                                            ]
                                        },
                                        "minItems": 1,
                                        "maxItems": 200,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1",
                                            "max:200"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Raster mode: array of pre-rendered bitmaps, 1–200 items."
                                    }
                                },
                                "required": [
                                    "design",
                                    "labels",
                                    "rasters"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success: true` and a `message`, or `qz: true` with `printer` and `payload_base64` for client-side printing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "configured": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "qz": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "printer": {
                                            "type": "string"
                                        },
                                        "payload_base64": {},
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "502": {
                        "description": "The printer could not be reached or the write failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "configured": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/product_batches": {
            "get": {
                "operationId": "get_api_product_batches",
                "tags": [
                    "Product Batches"
                ],
                "summary": "List batches",
                "description": "Paginated batches with product, variant and warehouse labels. Each row: `id, batch_no, product_id, product_name, product_code, generic_name, strength, dosage_form, variant_name, warehouse_id, warehouse_name, expiry_date, mfg_date, qty, unit_cost, status, days_to_expiry, expiry_bucket, notes`. `expiry_warning_days` echoes the system setting used for the *near expiry* window (default 90). `search` matches batch number, product name and generic name. `limit` is capped at 200; default sort is `expiry_date asc` (allowed: `id, batch_no, expiry_date, mfg_date, qty, status, created_at`). Returns an empty list when the module is not installed.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductBatchController@index",
                "x-source": "app/Http/Controllers/ProductBatchController.php#L31-L152",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "ProductBatch",
                    "Setting",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "expiry_window",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`expired` (before today), `near` (today … today + warning days), `valid` (after the warning window or no expiry), `all` (default)."
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only batches of this product."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`active`, `quarantined`, `expired`, `written_off`, or `all`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only batches in this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`batches[]`, `totalRows`, `warehouses[]`, `expiry_warning_days`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "batches": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "id": {
                                            "type": "integer"
                                        },
                                        "batch_no": {
                                            "type": "string"
                                        },
                                        "product_id": {
                                            "type": "integer"
                                        },
                                        "product_name": {},
                                        "product_code": {},
                                        "generic_name": {},
                                        "strength": {},
                                        "dosage_form": {},
                                        "variant_name": {},
                                        "warehouse_id": {
                                            "type": "integer"
                                        },
                                        "warehouse_name": {},
                                        "expiry_date": {},
                                        "mfg_date": {
                                            "type": "string"
                                        },
                                        "qty": {
                                            "type": "number"
                                        },
                                        "unit_cost": {
                                            "type": "number"
                                        },
                                        "status": {
                                            "type": "string"
                                        },
                                        "days_to_expiry": {},
                                        "expiry_bucket": {},
                                        "notes": {
                                            "type": "string"
                                        },
                                        "expiry_warning_days": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/product_batches/{id}": {
            "delete": {
                "operationId": "delete_api_product_batches_id",
                "tags": [
                    "Product Batches"
                ],
                "summary": "Delete a batch",
                "description": "Soft-deletes the batch after writing it off (warehouse stock is decremented by the remaining quantity). Requires `writeoff_batches`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductBatchController@destroy",
                "x-source": "app/Http/Controllers/ProductBatchController.php#L254-L275",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "ProductBatch"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Batch id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_product_batches_id",
                "tags": [
                    "Product Batches"
                ],
                "summary": "Update a batch",
                "description": "Edits a batch. Changing `qty` applies the difference to the warehouse stock so on-hand quantities stay consistent. Fields are updated only when present in the payload.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductBatchController@update",
                "x-source": "app/Http/Controllers/ProductBatchController.php#L157-L207",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "ProductBatch"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Batch id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch_no": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Batch / lot number, max 100."
                                    },
                                    "expiry_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Expiry date or `null`."
                                    },
                                    "mfg_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Manufacturing date or `null`."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "qty": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New remaining quantity (`>= 0`)."
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "quarantined",
                                            "expired",
                                            "written_off"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "in:active,quarantined,expired,written_off"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`active`, `quarantined`, `expired` or `written_off`."
                                    },
                                    "unit_cost": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cost per unit for this batch."
                                    }
                                },
                                "required": [
                                    "batch_no"
                                ]
                            },
                            "example": {
                                "batch_no": "LOT-2409A",
                                "expiry_date": "2027-03-31",
                                "qty": 120,
                                "unit_cost": 2.4,
                                "status": "active"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the updated `batch`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "batch": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/product_batches/{id}/writeoff": {
            "post": {
                "operationId": "post_api_product_batches_id_writeoff",
                "tags": [
                    "Product Batches"
                ],
                "summary": "Write off a batch",
                "description": "Marks the batch `written_off`, sets its quantity to 0 and **decrements the warehouse stock** by the remaining quantity. The optional `reason` is appended to the batch notes as `[Write-off] …`. Calling it on an already written-off batch is a no-op.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductBatchController@writeOff",
                "x-source": "app/Http/Controllers/ProductBatchController.php#L214-L249",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "ProductBatch"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Batch id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Why the batch is written off (max 500)."
                                    }
                                }
                            },
                            "example": {
                                "reason": "Expired on shelf"
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, message: \"Batch written off\"}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Batch written off"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products": {
            "get": {
                "operationId": "get_api_products",
                "tags": [
                    "Products"
                ],
                "summary": "List products",
                "description": "Paginated product list for the Products screen. Each row carries the product identity (`id, code, name, type, image, category, brand, unit`), pricing (`cost, price`), tax/discount fields, flags (`is_active`, `not_selling`, `hide_from_online_store`…) and **stock**: `quantity` is the total across the caller's warehouses, or the stock of the single warehouse given in `warehouse_id`. Variant products are returned as one parent row with a `variants` array.\n\n`search` matches product name/code, **variant** name/code, category and brand names, so a scanned variant barcode finds its parent. `code` also matches variant codes. Results are limited to the warehouses assigned to the caller; a `warehouse_id` outside that scope is ignored. Also returns the `warehouses`, `categories`, `subcategories` and `brands` lookups.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@index",
                "x-source": "app/Http/Controllers/ProductsController.php#L49-L338",
                "x-route-name": "products.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "products_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "name",
                    "category_id",
                    "brand_id",
                    "sub_category_id"
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Product",
                    "product_warehouse",
                    "ProductVariant",
                    "Category",
                    "SubCategory",
                    "Brand"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "brand_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only products of this brand."
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only products in this category (primary category)."
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on product code **or** any variant code (`LIKE`)."
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on product name (`LIKE`)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` active products only, `0` inactive only. Omit for all."
                    },
                    {
                        "name": "sub_category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Only products in this sub-category."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Show stock for this warehouse only. Must be one of the caller's warehouses."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`products[]`, `totalRows` and the filter lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "subcategories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "products": [
                                        {
                                            "id": 12,
                                            "code": "78945612",
                                            "name": "Cotton T-Shirt",
                                            "type": "is_variant",
                                            "image": "12345678.png",
                                            "category": "Apparel",
                                            "brand": "Acme",
                                            "unit": "Pc",
                                            "cost": 0,
                                            "price": 0,
                                            "quantity": 140,
                                            "is_active": 1,
                                            "variants": [
                                                {
                                                    "id": 3,
                                                    "name": "M / Red",
                                                    "code": "78945612-M-R",
                                                    "price": 19.9,
                                                    "qte": 70
                                                }
                                            ]
                                        }
                                    ],
                                    "totalRows": 1,
                                    "warehouses": [
                                        {
                                            "id": 1,
                                            "name": "Main"
                                        }
                                    ],
                                    "categories": [],
                                    "subcategories": [],
                                    "brands": []
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_products",
                "tags": [
                    "Products"
                ],
                "summary": "Create a product",
                "description": "Creates a product of any `type`. Send `multipart/form-data` (image upload); JSON-valued fields are JSON strings.\n\n**Required by type**\n- all: `name`, `code` (unique across products and variants), `type`, `Type_barcode`, `category_id`, `tax_method`, `discount_method`\n- `is_single` / `is_combo`: `cost`, `price`, `unit_id`\n- `is_variant`: `unit_id`, `variants` (JSON array, each variant needs `text`, `code`, `cost`, `price`; codes must be unique)\n- `is_service`: `price`\n\n**Opening stock.** `warehouses` is a JSON object keyed by warehouse id `{\"1\": {\"qte\": 10, \"warehouse_location_id\": 3}}`; for variant products `variant_opening` is `{\"<warehouse_id>\": [qty of variant 0, qty of variant 1, …]}` in the order of `variants`. Opening quantities are written to stock **and** recorded as an automatic *Opening stock* adjustment so average-cost reports have a cost basis. Stock rows are created for **every** warehouse, with `qte 0` where nothing was given.\n\n**Combo.** `materiels` is a JSON array `[{\"product_id\": 5, \"quantity\": 2}]` of single products.\n\n**Optional modules** (ignored when the feature is off in settings): `packs` (multi-pack selling), `price_tiers` (wholesale ladder), `gtin`, pharmacy fields, pre-order fields, batch tracking. Gallery images are uploaded as `gallery_images[]`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@store",
                "x-source": "app/Http/Controllers/ProductsController.php#L411-L988",
                "x-route-name": "products.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "products_add",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "Warehouse",
                    "product_warehouse",
                    "ProductWarehouseLocation",
                    "Adjustment",
                    "AdjustmentDetail"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "TaxNet": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax rate in percent. Default `0`.",
                                        "type": "number"
                                    },
                                    "Type_barcode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Barcode symbology used when printing labels: `CODE128`, `CODE39`, `EAN13`, `EAN8`, `UPC`…"
                                    },
                                    "brand_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Brand id."
                                    },
                                    "category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Primary category id."
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-unique": "product_variants ->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "unique:products ->where",
                                            "unique:product_variants ->where"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product code / barcode. Unique among non-deleted products and variants."
                                    },
                                    "cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type == 'is_single' || $request->type == 'is_combo')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type == 'is_single' || $request->type == 'is_combo')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Purchase cost per base unit (single/combo)."
                                    },
                                    "discount": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default line discount applied to the product. Default `0`.",
                                        "type": "number"
                                    },
                                    "discount_method": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`1` = percentage, `2` = fixed amount.",
                                        "type": "integer"
                                    },
                                    "dosage_form": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy: tablet, syrup, capsule…"
                                    },
                                    "drug_schedule": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy: regulatory schedule / class."
                                    },
                                    "faqs": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of `{\"question\":\"…\",\"answer\":\"…\"}` (max 30) shown on the storefront product page.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "generic_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy: generic / molecule name."
                                    },
                                    "gtin": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Global trade item number (GTIN / UPC / EAN / ISBN), max 64. Shown only when enabled in settings."
                                    },
                                    "guarantee_period": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guarantee duration number.",
                                        "type": "integer"
                                    },
                                    "guarantee_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guarantee unit: `days`, `months`, `years`."
                                    },
                                    "has_guarantee": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` when a money-back guarantee applies."
                                    },
                                    "height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Height (shipping).",
                                        "type": "number"
                                    },
                                    "hide_from_online_store": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` keeps the product out of the online store.",
                                        "type": "boolean"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Main image file (jpg, jpeg, png, gif, webp); resized per settings."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`false` deactivates the product everywhere. Default `true`."
                                    },
                                    "is_batch_tracked": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` to track batches with expiry dates (pharmacy / food)."
                                    },
                                    "is_classified": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` marks a classified-ad / listing product (quote request instead of cart)."
                                    },
                                    "is_featured": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` shows the product in the storefront's featured section."
                                    },
                                    "is_imei": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` to track serial / IMEI numbers per unit."
                                    },
                                    "is_preorder": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` allows ordering while out of stock."
                                    },
                                    "is_returnable": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`false` forbids returns of this product from the storefront. Default `true`."
                                    },
                                    "is_variant": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` when the product has variants (mirror of `type = is_variant`)."
                                    },
                                    "labels": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of up to 5 short badge labels (≤ 30 chars each), e.g. `[\"New\",\"Hot\"]`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "length": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Length (shipping).",
                                        "type": "number"
                                    },
                                    "manufacturer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Manufacturer name."
                                    },
                                    "materiels": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of combo components `[{\"product_id\":5,\"quantity\":2}]` (combo only).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "min_price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Minimum selling price; POS will not discount below it. Default `0`."
                                    },
                                    "multi_category_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ordered JSON array of category ids when a product belongs to several categories; the first one becomes `category_id`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "multi_subcategory_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ordered JSON array of sub-category ids; the first becomes `sub_category_id`. Empty array clears sub-categories.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-rules": [
                                            "regex:/^[^<>]*$/"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255",
                                            "regex:/^[^<>]*$/"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product name, max 255 chars, may not contain `<` or `>`."
                                    },
                                    "not_selling": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` hides the product from POS and sales (purchase-only item).",
                                        "type": "boolean"
                                    },
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Long description / notes (HTML not allowed)."
                                    },
                                    "pack_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy: pack size text.",
                                        "type": "string"
                                    },
                                    "packs": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of multi-pack options (needs *multi-pack selling*): `[{\"name\":\"Box of 6\",\"qty\":6,\"price\":99,\"is_default\":false,\"product_variant_id\":null}]`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty points earned per unit sold. Default `0`.",
                                        "type": "number"
                                    },
                                    "preorder_always": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "With `is_preorder`: keep pre-order mode even when stock exists.",
                                        "type": "boolean"
                                    },
                                    "preorder_available_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Expected availability date shown to shoppers (`YYYY-MM-DD`)."
                                    },
                                    "preorder_limit": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Maximum pre-order quantity.",
                                        "type": "integer"
                                    },
                                    "preorder_note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Message shown on the storefront for pre-orders."
                                    },
                                    "prescription_required": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy: `true` when a prescription is required to sell.",
                                        "type": "boolean"
                                    },
                                    "price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_variant')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_variant')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Retail selling price per base unit (all types except variant, where each variant has its own)."
                                    },
                                    "price_tiers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of quantity price brackets (needs *wholesale pricing*): `[{\"min_qty\":10,\"max_qty\":49,\"price\":17.5},{\"min_qty\":50,\"max_qty\":null,\"price\":16}]`. Brackets may not overlap.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "related_product_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of product ids shown as *related products*.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "shelf_life_days": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default shelf life in days used to suggest expiry dates for new batches.",
                                        "type": "integer"
                                    },
                                    "shipping_method_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of shipping method ids allowed for this product (storefront).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "size_guide_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Size guide id to display on the storefront."
                                    },
                                    "stock_alert": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Quantity at or below which the product appears in stock alerts. Default `0`.",
                                        "type": "number"
                                    },
                                    "strength": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy: strength, e.g. `500 mg`."
                                    },
                                    "sub_category_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Primary sub-category id."
                                    },
                                    "tags": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of tag strings (max 30).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "tax_method": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`1` = tax exclusive (added on top), `2` = tax inclusive.",
                                        "type": "integer"
                                    },
                                    "type": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "`is_single`, `is_variant`, `is_service` or `is_combo`.",
                                        "type": "string"
                                    },
                                    "unit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_service')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_service')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Base unit id (required unless `is_service`)."
                                    },
                                    "unit_purchase_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase unit id. Defaults to `unit_id`."
                                    },
                                    "unit_sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale unit id (a sub-unit of the base unit). Defaults to `unit_id`."
                                    },
                                    "variant_images": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Array of image files, one per variant, indexed like `variants` (`variant_images[0]`, `variant_images[1]`…)."
                                    },
                                    "variant_opening": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON object of opening stock per warehouse for variant products: `{\"1\":[10,5],\"2\":[0,3]}` (array index = variant position).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "variants": {
                                        "x-rules": [
                                            "custom-closure-rule"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "custom-closure-rule"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "JSON array of variants for `is_variant`: `[{\"text\":\"M / Red\",\"code\":\"TS-M-R\",\"cost\":8,\"price\":19.9,\"wholesale\":15,\"min_price\":12,\"gtin\":\"…\",\"image\":\"…\"}]`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "warehouses": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON object keyed by warehouse id with opening stock and shelf location: `{\"1\":{\"qte\":10,\"warehouse_location_id\":3}}`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "warranty_period": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty duration number.",
                                        "type": "integer"
                                    },
                                    "warranty_terms": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty terms text."
                                    },
                                    "warranty_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty unit: `days`, `months` or `years`."
                                    },
                                    "weight": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Weight (shipping).",
                                        "type": "number"
                                    },
                                    "wholesale_price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wholesale price (used when the customer/sale is wholesale). Default `0`."
                                    },
                                    "width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Width (shipping).",
                                        "type": "number"
                                    },
                                    "gallery_images": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "Additional gallery images (`gallery_images[]`).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gallery_urls": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON array of remote image URLs to import into the gallery.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gallery_new_manifest": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON array describing the uploaded gallery files (order, `is_main`).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "Type_barcode",
                                    "category_id",
                                    "code",
                                    "discount_method",
                                    "name",
                                    "tax_method",
                                    "type",
                                    "variants"
                                ]
                            },
                            "example": {
                                "type": "is_single",
                                "name": "Cotton T-Shirt",
                                "code": "78945612",
                                "Type_barcode": "CODE128",
                                "category_id": 2,
                                "brand_id": 1,
                                "unit_id": 1,
                                "cost": 8.5,
                                "price": 19.9,
                                "tax_method": 1,
                                "TaxNet": 10,
                                "discount_method": 1,
                                "discount": 0,
                                "stock_alert": 5,
                                "is_active": "true",
                                "warehouses": "{\"1\":{\"qte\":50,\"warehouse_location_id\":null}}",
                                "tags": "[\"summer\",\"cotton\"]"
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/create": {
            "get": {
                "operationId": "get_api_products_create",
                "tags": [
                    "Products"
                ],
                "summary": "Get lookups for the product form",
                "description": "Everything the *create product* form needs: `categories`, `subcategories` (with `category_id`), `brands`, `size_guides`, `shipping_methods`, base `units`, the caller's `warehouses` (each with `qte: 0` placeholder for opening stock) and their active `warehouse_locations`, plus the feature flags `show_product_gtin`, `show_serial_tracking`, `enable_multi_pack_selling`, `enable_wholesale_pricing`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@create",
                "x-source": "app/Http/Controllers/ProductsController.php#L2604-L2668",
                "x-route-name": "products.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "products_add",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Category",
                    "SubCategory",
                    "Brand",
                    "SizeGuide",
                    "ShippingMethod",
                    "Unit",
                    "Warehouse",
                    "UserWarehouse",
                    "WarehouseLocation",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "Lookup lists and feature flags.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "qte": {
                                            "type": "integer",
                                            "example": 0
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "subcategories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "size_guides": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "shipping_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "units": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouse_locations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "show_product_gtin": {},
                                        "show_serial_tracking": {},
                                        "enable_multi_pack_selling": {},
                                        "enable_wholesale_pricing": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/delete/by_selection": {
            "post": {
                "operationId": "post_api_products_delete_by_selection",
                "tags": [
                    "Products"
                ],
                "summary": "Delete several products",
                "description": "Soft-deletes every product in `selectedIds` with the same side effects as the single delete, inside one transaction.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@delete_by_selection",
                "x-source": "app/Http/Controllers/ProductsController.php#L1708-L1750",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "products_delete",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of product ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            },
                            "example": {
                                "selectedIds": [
                                    12,
                                    13
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/import/service": {
            "post": {
                "operationId": "post_api_products_import_service",
                "tags": [
                    "Products"
                ],
                "summary": "Import service products from Excel",
                "description": "Creates `is_service` products (cost always 0, no stock) from an `.xls`/`.xlsx` file. Columns: `name`, `code`, `retail_price` (or `price`), `category`, `unit`, optional `sub_category`, `wholesale_price`, `min_price`, `brand`, `note`. Same uniqueness and abort-on-first-error behaviour as the single import.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@import_service_products",
                "x-source": "app/Http/Controllers/ProductsController.php#L3321-L3498",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_import",
                        "slug": "product_import",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "Product",
                    "ProductVariant",
                    "Category",
                    "SubCategory",
                    "Unit",
                    "Brand"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:xls,xlsx",
                                        "x-laravel-rules": [
                                            "required",
                                            "mimes:xls,xlsx"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Spreadsheet file."
                                    }
                                },
                                "required": [
                                    "products"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{status: true}` or `{status: false, message}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/import/single": {
            "post": {
                "operationId": "post_api_products_import_single",
                "tags": [
                    "Products"
                ],
                "summary": "Import single products from Excel",
                "description": "Creates `is_single` products from an `.xls`/`.xlsx` file with a header row. Columns: `name`, `code`, `retail_price` (or `price`), `cost`, `category`, `unit`, optional `sub_category`, `brand`, `stock_alert`, `note`, `wholesale_price`, `min_price`. Categories, sub-categories and brands are created on the fly when unknown; the unit must already exist (matched on short name or name). Codes must be unique in the file and in the database. Validation stops at the **first** bad row and nothing is imported (`status: false` + `message`). Stock rows are created with quantity 0 for all warehouses.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@import_single_products",
                "x-source": "app/Http/Controllers/ProductsController.php#L3120-L3315",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_import",
                        "slug": "product_import",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "Product",
                    "ProductVariant",
                    "Category",
                    "SubCategory",
                    "Unit",
                    "Brand"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:xls,xlsx",
                                        "x-laravel-rules": [
                                            "required",
                                            "mimes:xls,xlsx"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Spreadsheet file."
                                    }
                                },
                                "required": [
                                    "products"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{status: true}` on success, or `{status: false, message}` describing the first problem.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/import/update-only": {
            "post": {
                "operationId": "post_api_products_import_update_only",
                "tags": [
                    "Products"
                ],
                "summary": "Bulk-update cost and price by code",
                "description": "Updates **existing** products matched by `code` from a `.csv`, `.xls` or `.xlsx` file with columns `code`, `cost`, `retail_price` (or `price`). Only cost and retail price change; unknown codes are reported in `not_found`, invalid rows in `errors`, and valid rows are still applied.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@import_update_only",
                "x-source": "app/Http/Controllers/ProductsController.php#L3832-L3982",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_import",
                        "slug": "product_import",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "x-rules": [
                                            "custom-closure-rule"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "custom-closure-rule"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "CSV or spreadsheet file.",
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "required": [
                                    "products"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "Counts of updated rows plus `not_found[]` and `errors[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {},
                                        "message": {
                                            "type": "string"
                                        },
                                        "updated": {},
                                        "not_found": {
                                            "type": "integer"
                                        },
                                        "errors": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "status": true,
                                    "message": "Import completed: 40 updated, 2 not found, 0 errors",
                                    "updated": 40,
                                    "not_found": [
                                        "X-100",
                                        "X-101"
                                    ],
                                    "errors": []
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/import/variants": {
            "post": {
                "operationId": "post_api_products_import_variants",
                "tags": [
                    "Products"
                ],
                "summary": "Import variant products from Excel",
                "description": "Creates `is_variant` products with their variants from an `.xls`/`.xlsx` file. Each row is one **variant**; rows sharing the same `product_code` form one parent. Columns: `product_code` (or `code`/`parent_code`), `product_name` (or `name`), `category`, optional `sub_category`, `unit`, `brand`, `type` (if present must be `is_variant`), then per variant `variant_name`, `variant_code` (or `sku`), `variant_cost`, `variant_price`, optional `variant_wholesale`, `variant_min_price`. All codes must be unique in the file and the database. Whole-file validation: the first problem aborts the import.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@import_variant_products",
                "x-source": "app/Http/Controllers/ProductsController.php#L3500-L3825",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_import",
                        "slug": "product_import",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "Product",
                    "ProductVariant",
                    "Category",
                    "SubCategory",
                    "Unit",
                    "Brand",
                    "product_warehouse"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:xls,xlsx",
                                        "x-laravel-rules": [
                                            "required",
                                            "mimes:xls,xlsx"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Spreadsheet file."
                                    }
                                },
                                "required": [
                                    "products"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{status: true}` or `{status: false, message}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/search-basic": {
            "get": {
                "operationId": "get_api_products_search_basic",
                "tags": [
                    "Products"
                ],
                "summary": "Search products by name or code (typeahead)",
                "description": "Lightweight typeahead used by the *Related products* picker: up to 25 active products matching `q` on name or code, returned as `{id, name, code}` ordered by name.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@search_products_basic",
                "x-source": "app/Http/Controllers/ProductsController.php#L4129-L4147",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "products_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "exclude",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product id to leave out (the product being edited)."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search text (name or code, `LIKE`). Empty returns the first 25 products."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`products[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "products": [
                                        {
                                            "id": 5,
                                            "name": "Cotton T-Shirt",
                                            "code": "78945612"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/warehouse_locations": {
            "post": {
                "operationId": "post_api_products_warehouse_locations",
                "tags": [
                    "Products"
                ],
                "summary": "Create a shelf location from the product form",
                "description": "Quick-create of a warehouse location (bin / shelf code) without leaving the product form. `code` must be unique within the warehouse. Requires `products_add` rather than the warehouse-location permission.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@storeWarehouseLocation",
                "x-source": "app/Http/Controllers/ProductsController.php#L343-L380",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "products_add",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "WarehouseLocation"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-unique": "warehouse_locations ->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64",
                                            "unique:warehouse_locations ->where"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Location code, max 64, unique per warehouse."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Optional descriptive name, max 192."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-enum-source": "$allowedWarehouseIds",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "in:$allowedWarehouseIds"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id; must be one of the caller's warehouses."
                                    }
                                },
                                "required": [
                                    "code",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "warehouse_id": 1,
                                "code": "A-03-2",
                                "name": "Aisle A, rack 3, shelf 2"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The created `location`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "location": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "location": {
                                        "id": 9,
                                        "warehouse_id": 1,
                                        "code": "A-03-2",
                                        "name": "Aisle A, rack 3, shelf 2",
                                        "is_active": 1
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/{id}/duplicate": {
            "post": {
                "operationId": "post_api_products_id_duplicate",
                "tags": [
                    "Products"
                ],
                "summary": "Duplicate a product",
                "description": "Creates a copy of the product with a new generated `code`, copied main image and gallery, the same categories/sub-categories, copied variants (new codes `<variant name>-<new code>`, quantity 0) and combo components. Stock is **not** copied: stock rows are created with `qte 0` for every warehouse. Returns the new product id.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@duplicate",
                "x-source": "app/Http/Controllers/ProductsController.php#L4479-L4601",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "products_add",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "ProductImage",
                    "ProductVariant",
                    "CombinedProduct",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id to copy."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "New product `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "id": 57
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/{id}/fitments": {
            "get": {
                "operationId": "get_api_products_id_fitments",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Get a product's fitments",
                "description": "The product (`id, name, code`) and its fitment rows: `id, vehicle_make_id, vehicle_model_id, make_name, model_name, year_from, year_to, engine, notes`. A `null` model means *all models of the make*.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@productFitments",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L158-L183",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "products_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "ProductFitment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`product` and `fitments[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "name": {},
                                                "code": {}
                                            }
                                        },
                                        "fitments": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_products_id_fitments",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Replace a product's fitments",
                "description": "Replace-all save: existing fitment rows are deleted and the submitted list (max 200) inserted. A model must belong to its make (`422` otherwise); swapped year bounds are corrected. Send an empty array to make the product universal. Returns the same payload as *Get a product's fitments*.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@saveProductFitments",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L186-L238",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    },
                    {
                        "ability": "view",
                        "slug": "products_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "VehicleModel",
                    "ProductFitment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "fitments": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "engine": {
                                                    "type": "string",
                                                    "maxLength": 100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Engine code / description, max 100."
                                                },
                                                "notes": {
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:255"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Notes, max 255."
                                                },
                                                "vehicle_make_id": {
                                                    "type": "integer",
                                                    "x-exists": "vehicle_makes,id",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer",
                                                        "exists:vehicle_makes,id"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Make id."
                                                },
                                                "vehicle_model_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-exists": "vehicle_models,id",
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer",
                                                        "exists:vehicle_models,id"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Model id, or `null` for all models."
                                                },
                                                "year_from": {
                                                    "type": "integer",
                                                    "minimum": 1900,
                                                    "maximum": 2100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer",
                                                        "min:1900",
                                                        "max:2100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "First model year (1900–2100)."
                                                },
                                                "year_to": {
                                                    "type": "integer",
                                                    "minimum": 1900,
                                                    "maximum": 2100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer",
                                                        "min:1900",
                                                        "max:2100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Last model year (1900–2100)."
                                                }
                                            },
                                            "required": [
                                                "vehicle_make_id"
                                            ]
                                        },
                                        "maxItems": 200,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array",
                                            "max:200"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Array of fitment rows (max 200)."
                                    }
                                }
                            },
                            "example": {
                                "fitments": [
                                    {
                                        "vehicle_make_id": 1,
                                        "vehicle_model_id": 10,
                                        "year_from": 2014,
                                        "year_to": 2019,
                                        "engine": "1.8 VVT-i"
                                    }
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`product` and the saved `fitments[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "name": {},
                                                "code": {}
                                            }
                                        },
                                        "fitments": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/{id}/opening_batches": {
            "get": {
                "operationId": "get_api_products_id_opening_batches",
                "tags": [
                    "Product Batches"
                ],
                "summary": "Get unbatched stock per warehouse",
                "description": "For the *Opening batch & expiry* section of the product form: one row per warehouse (restricted to the caller's) with the stock on hand, the quantity already assigned to batches and the **unbatched** remainder that predates batch tracking. `supported: false` when the module is not installed.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductBatchController@openingMeta",
                "x-source": "app/Http/Controllers/ProductBatchController.php#L284-L301",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`supported` and `rows[]` (`warehouse_id, warehouse_name, on_hand, batched, unbatched`, per variant when relevant).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supported": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "rows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_products_id_opening_batches",
                "tags": [
                    "Product Batches"
                ],
                "summary": "Assign existing stock to opening batches",
                "description": "Labels stock that already exists in a warehouse with batch numbers and expiry dates so FEFO can sell it. **Warehouse stock is not changed** — the sum of `batches[].qty` may not exceed the unbatched quantity (`422` otherwise).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductBatchController@storeOpening",
                "x-source": "app/Http/Controllers/ProductBatchController.php#L310-L344",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batches": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "batch_no": {
                                                    "type": "string",
                                                    "maxLength": 100,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "string",
                                                        "max:100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Lot number, max 100."
                                                },
                                                "expiry_date": {
                                                    "type": "string",
                                                    "format": "date",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "date"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Expiry date."
                                                },
                                                "mfg_date": {
                                                    "type": "string",
                                                    "format": "date",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "date"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Manufacturing date."
                                                },
                                                "notes": {
                                                    "type": "string",
                                                    "maxLength": 500,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:500"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Notes, max 500."
                                                },
                                                "qty": {
                                                    "type": "number",
                                                    "x-rules": [
                                                        "gt:0"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "numeric",
                                                        "gt:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity assigned to this batch (`> 0`)."
                                                },
                                                "unit_cost": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Unit cost."
                                                }
                                            },
                                            "required": [
                                                "batch_no",
                                                "qty"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Array of batches to create (at least one)."
                                    },
                                    "product_variant_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Variant id for variant products."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse holding the stock."
                                    }
                                },
                                "required": [
                                    "batches",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "warehouse_id": 1,
                                "batches": [
                                    {
                                        "batch_no": "LOT-2409A",
                                        "qty": 80,
                                        "expiry_date": "2027-03-31",
                                        "unit_cost": 2.4
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the created `batches[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "batches": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products/{product}": {
            "delete": {
                "operationId": "delete_api_products_product",
                "tags": [
                    "Products"
                ],
                "summary": "Delete a product",
                "description": "Soft-deletes the product, its variants and its stock rows, detaches multi-categories, and removes the main image and gallery files from disk. Documents that reference the product keep their lines.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@destroy",
                "x-source": "app/Http/Controllers/ProductsController.php#L1665-L1704",
                "x-route-name": "products.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "products_delete",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_products_product",
                "tags": [
                    "Products"
                ],
                "summary": "(Not implemented) Get a product",
                "description": "Resource stub with an empty body; returns an empty `200`. Use `GET /api/get_product_detail/{id}` (read-only detail) or `GET /api/products/{product}/edit`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@show",
                "x-source": "app/Http/Controllers/ProductsController.php#L2182-L2185",
                "x-route-name": "products.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Product id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_products_product",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Products"
                ],
                "summary": "Update a product",
                "description": "Updates a product with the same payload as *Create a product*. Differences:\n\n- `code` uniqueness ignores the product's own row and its own variants.\n- `variants` is sent as an array (JSON string) of `{id?, text, code, cost, price, …}`: variants with an `id` are updated, new ones are inserted, missing ones are soft-deleted (their stock rows too).\n- Opening stock (`warehouses[].qte`) is **not** applied on update; stock changes go through adjustments. `warehouse_locations` / `warehouses[].warehouse_location_id` still update the shelf location per warehouse.\n- Gallery: existing images are managed through `product_gallery_json` (order, main image, deletions) while new files come in `gallery_images[]`.\n- Sending `image` replaces and deletes the previous main image.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@update",
                "x-source": "app/Http/Controllers/ProductsController.php#L993-L1660",
                "x-route-name": "products.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "Warehouse",
                    "product_warehouse",
                    "UserWarehouse",
                    "ProductWarehouseLocation"
                ],
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Product id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "TaxNet": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent.",
                                        "type": "number"
                                    },
                                    "Type_barcode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Barcode symbology."
                                    },
                                    "brand_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Brand id."
                                    },
                                    "category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Primary category id."
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-unique": "product_variants ->ignore->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "unique:products ->ignore->where",
                                            "unique:product_variants ->ignore->where"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product code, unique."
                                    },
                                    "cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type == 'is_single' || $request->type == 'is_combo')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type == 'is_single' || $request->type == 'is_combo')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cost (single/combo)."
                                    },
                                    "discount": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default discount.",
                                        "type": "number"
                                    },
                                    "discount_method": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`1` percent, `2` fixed.",
                                        "type": "integer"
                                    },
                                    "dosage_form": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy dosage form."
                                    },
                                    "drug_schedule": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Drug schedule."
                                    },
                                    "faqs": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of `{question, answer}`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "generic_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy generic name."
                                    },
                                    "gtin": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "GTIN / UPC / EAN / ISBN, max 64."
                                    },
                                    "guarantee_period": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guarantee duration.",
                                        "type": "integer"
                                    },
                                    "guarantee_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`days`/`months`/`years`."
                                    },
                                    "has_guarantee": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guarantee flag."
                                    },
                                    "height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Height.",
                                        "type": "number"
                                    },
                                    "hide_from_online_store": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide from storefront.",
                                        "type": "boolean"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "New main image file."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "is_batch_tracked": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Batch & expiry tracking."
                                    },
                                    "is_classified": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Classified-ad product."
                                    },
                                    "is_featured": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Storefront featured flag."
                                    },
                                    "is_imei": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Serial / IMEI tracking."
                                    },
                                    "is_preorder": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow pre-orders."
                                    },
                                    "is_returnable": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow storefront returns."
                                    },
                                    "labels": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of up to 5 badge labels.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "length": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Length.",
                                        "type": "number"
                                    },
                                    "manufacturer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Manufacturer."
                                    },
                                    "materiels": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of combo components.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "min_price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Minimum selling price."
                                    },
                                    "multi_category_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ordered JSON array of category ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "multi_subcategory_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ordered JSON array of sub-category ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-rules": [
                                            "regex:/^[^<>]*$/"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255",
                                            "regex:/^[^<>]*$/"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product name, max 255, no `<` / `>`."
                                    },
                                    "not_selling": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide from POS/sales.",
                                        "type": "boolean"
                                    },
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "pack_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy pack size.",
                                        "type": "string"
                                    },
                                    "packs": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of multi-pack options.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty points per unit.",
                                        "type": "number"
                                    },
                                    "preorder_always": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Always pre-order.",
                                        "type": "boolean"
                                    },
                                    "preorder_available_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Availability date."
                                    },
                                    "preorder_limit": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Max pre-order qty.",
                                        "type": "integer"
                                    },
                                    "preorder_note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pre-order message."
                                    },
                                    "prescription_required": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Prescription needed.",
                                        "type": "boolean"
                                    },
                                    "price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_variant')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_variant')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Retail price (non-variant)."
                                    },
                                    "price_tiers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of quantity price brackets.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "related_product_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of related product ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "shelf_life_days": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default shelf life in days.",
                                        "type": "integer"
                                    },
                                    "shipping_method_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of shipping method ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "size_guide_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Size guide id."
                                    },
                                    "stock_alert": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Low-stock threshold.",
                                        "type": "number"
                                    },
                                    "strength": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy strength."
                                    },
                                    "sub_category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Primary sub-category id."
                                    },
                                    "tags": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of tags.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "tax_method": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`1` exclusive, `2` inclusive.",
                                        "type": "integer"
                                    },
                                    "type": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "`is_single`, `is_variant`, `is_service` or `is_combo`.",
                                        "type": "string"
                                    },
                                    "unit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_service')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_service')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Base unit id (required unless service)."
                                    },
                                    "unit_purchase_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase unit id."
                                    },
                                    "unit_sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale unit id."
                                    },
                                    "variant_images": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Image files indexed like `variants`."
                                    },
                                    "variants": {
                                        "x-rules": [
                                            "custom-closure-rule"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "custom-closure-rule"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "JSON array of variants `[{\"id\":3,\"text\":\"M / Red\",\"code\":\"TS-M-R\",\"cost\":8,\"price\":19.9}]`; omit `id` for new variants.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "warehouse_locations": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON object `{\"<warehouse_id>\": <warehouse_location_id>}` — alternative way to set shelf locations.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "warranty_period": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty duration.",
                                        "type": "integer"
                                    },
                                    "warranty_terms": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty terms."
                                    },
                                    "warranty_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`days`/`months`/`years`."
                                    },
                                    "weight": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Weight.",
                                        "type": "number"
                                    },
                                    "wholesale_price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wholesale price."
                                    },
                                    "width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Width.",
                                        "type": "number"
                                    },
                                    "gallery_images": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "New gallery image files.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gallery_urls": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON array of remote image URLs to add.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gallery_new_manifest": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON manifest for the newly uploaded gallery files.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "product_gallery_json": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON array of the existing gallery images with their new `sort_order` / `is_main`; images missing from it are deleted.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "category_id",
                                    "code",
                                    "discount_method",
                                    "name",
                                    "tax_method",
                                    "type",
                                    "variants"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_products_product",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Products"
                ],
                "summary": "Update a product",
                "description": "Updates a product with the same payload as *Create a product*. Differences:\n\n- `code` uniqueness ignores the product's own row and its own variants.\n- `variants` is sent as an array (JSON string) of `{id?, text, code, cost, price, …}`: variants with an `id` are updated, new ones are inserted, missing ones are soft-deleted (their stock rows too).\n- Opening stock (`warehouses[].qte`) is **not** applied on update; stock changes go through adjustments. `warehouse_locations` / `warehouses[].warehouse_location_id` still update the shelf location per warehouse.\n- Gallery: existing images are managed through `product_gallery_json` (order, main image, deletions) while new files come in `gallery_images[]`.\n- Sending `image` replaces and deletes the previous main image.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@update",
                "x-source": "app/Http/Controllers/ProductsController.php#L993-L1660",
                "x-route-name": "products.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "Warehouse",
                    "product_warehouse",
                    "UserWarehouse",
                    "ProductWarehouseLocation"
                ],
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Product id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "TaxNet": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent.",
                                        "type": "number"
                                    },
                                    "Type_barcode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Barcode symbology."
                                    },
                                    "brand_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Brand id."
                                    },
                                    "category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Primary category id."
                                    },
                                    "code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-unique": "product_variants ->ignore->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "unique:products ->ignore->where",
                                            "unique:product_variants ->ignore->where"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product code, unique."
                                    },
                                    "cost": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type == 'is_single' || $request->type == 'is_combo')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type == 'is_single' || $request->type == 'is_combo')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cost (single/combo)."
                                    },
                                    "discount": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default discount.",
                                        "type": "number"
                                    },
                                    "discount_method": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`1` percent, `2` fixed.",
                                        "type": "integer"
                                    },
                                    "dosage_form": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy dosage form."
                                    },
                                    "drug_schedule": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Drug schedule."
                                    },
                                    "faqs": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of `{question, answer}`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "generic_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy generic name."
                                    },
                                    "gtin": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "GTIN / UPC / EAN / ISBN, max 64."
                                    },
                                    "guarantee_period": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guarantee duration.",
                                        "type": "integer"
                                    },
                                    "guarantee_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`days`/`months`/`years`."
                                    },
                                    "has_guarantee": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guarantee flag."
                                    },
                                    "height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Height.",
                                        "type": "number"
                                    },
                                    "hide_from_online_store": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide from storefront.",
                                        "type": "boolean"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "New main image file."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "is_batch_tracked": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Batch & expiry tracking."
                                    },
                                    "is_classified": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Classified-ad product."
                                    },
                                    "is_featured": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Storefront featured flag."
                                    },
                                    "is_imei": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Serial / IMEI tracking."
                                    },
                                    "is_preorder": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow pre-orders."
                                    },
                                    "is_returnable": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow storefront returns."
                                    },
                                    "labels": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of up to 5 badge labels.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "length": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Length.",
                                        "type": "number"
                                    },
                                    "manufacturer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Manufacturer."
                                    },
                                    "materiels": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of combo components.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "min_price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Minimum selling price."
                                    },
                                    "multi_category_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ordered JSON array of category ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "multi_subcategory_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Ordered JSON array of sub-category ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-rules": [
                                            "regex:/^[^<>]*$/"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255",
                                            "regex:/^[^<>]*$/"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product name, max 255, no `<` / `>`."
                                    },
                                    "not_selling": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide from POS/sales.",
                                        "type": "boolean"
                                    },
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "pack_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy pack size.",
                                        "type": "string"
                                    },
                                    "packs": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of multi-pack options.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty points per unit.",
                                        "type": "number"
                                    },
                                    "preorder_always": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Always pre-order.",
                                        "type": "boolean"
                                    },
                                    "preorder_available_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Availability date."
                                    },
                                    "preorder_limit": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Max pre-order qty.",
                                        "type": "integer"
                                    },
                                    "preorder_note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pre-order message."
                                    },
                                    "prescription_required": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Prescription needed.",
                                        "type": "boolean"
                                    },
                                    "price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_variant')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_variant')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Retail price (non-variant)."
                                    },
                                    "price_tiers": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of quantity price brackets.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "related_product_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of related product ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "shelf_life_days": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default shelf life in days.",
                                        "type": "integer"
                                    },
                                    "shipping_method_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of shipping method ids.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "size_guide_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Size guide id."
                                    },
                                    "stock_alert": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Low-stock threshold.",
                                        "type": "number"
                                    },
                                    "strength": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy strength."
                                    },
                                    "sub_category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Primary sub-category id."
                                    },
                                    "tags": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array of tags.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "tax_method": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`1` exclusive, `2` inclusive.",
                                        "type": "integer"
                                    },
                                    "type": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "`is_single`, `is_variant`, `is_service` or `is_combo`.",
                                        "type": "string"
                                    },
                                    "unit_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_service')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::requiredIf($request->type != 'is_service')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Base unit id (required unless service)."
                                    },
                                    "unit_purchase_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase unit id."
                                    },
                                    "unit_sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale unit id."
                                    },
                                    "variant_images": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Image files indexed like `variants`."
                                    },
                                    "variants": {
                                        "x-rules": [
                                            "custom-closure-rule"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "custom-closure-rule"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "JSON array of variants `[{\"id\":3,\"text\":\"M / Red\",\"code\":\"TS-M-R\",\"cost\":8,\"price\":19.9}]`; omit `id` for new variants.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "warehouse_locations": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON object `{\"<warehouse_id>\": <warehouse_location_id>}` — alternative way to set shelf locations.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "warranty_period": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty duration.",
                                        "type": "integer"
                                    },
                                    "warranty_terms": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warranty terms."
                                    },
                                    "warranty_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`days`/`months`/`years`."
                                    },
                                    "weight": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Weight.",
                                        "type": "number"
                                    },
                                    "wholesale_price": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Wholesale price."
                                    },
                                    "width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Width.",
                                        "type": "number"
                                    },
                                    "gallery_images": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary"
                                        },
                                        "description": "New gallery image files.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gallery_urls": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON array of remote image URLs to add.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gallery_new_manifest": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON manifest for the newly uploaded gallery files.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "product_gallery_json": {
                                        "type": "string",
                                        "x-format": "JSON-encoded string",
                                        "description": "JSON array of the existing gallery images with their new `sort_order` / `is_main`; images missing from it are deleted.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "category_id",
                                    "code",
                                    "discount_method",
                                    "name",
                                    "tax_method",
                                    "type",
                                    "variants"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/products/{product}/edit": {
            "get": {
                "operationId": "get_api_products_product_edit",
                "tags": [
                    "Products"
                ],
                "summary": "Get a product for editing",
                "description": "Returns the product in the shape the edit form expects (`product`), together with all lookups (`categories`, `all_subcategories`, `brands`, `size_guides`, `shipping_methods`, `units`, `units_sub`, `materiels` for combos, `warehouses`, `warehouse_locations`, `product_warehouse_locations`) and the feature flags. Ids of deleted categories/brands/units are blanked so the form does not show dangling references. For variant products `product.variants` lists each variant with its `qty`, `packs` and images; for combos `product.materiels` lists the components; gallery images come back as `product.images[]` (`id, image_path, url, is_main, sort_order`).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@edit",
                "x-source": "app/Http/Controllers/ProductsController.php#L2790-L3113",
                "x-route-name": "products.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "Category",
                    "SubCategory",
                    "Brand",
                    "Unit",
                    "CombinedProduct",
                    "ProductVariant",
                    "ProductPack",
                    "ProductPriceTier",
                    "ProductImage",
                    "SizeGuide",
                    "ShippingMethod",
                    "Warehouse",
                    "UserWarehouse",
                    "WarehouseLocation",
                    "ProductWarehouseLocation",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`product` object plus lookups and flags.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product_id": {},
                                        "name": {},
                                        "code": {},
                                        "unit_name": {},
                                        "cost": {},
                                        "quantity": {},
                                        "id": {},
                                        "image_path": {},
                                        "url": {},
                                        "is_main": {
                                            "type": "boolean"
                                        },
                                        "sort_order": {
                                            "type": "integer"
                                        },
                                        "product": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "all_subcategories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "size_guides": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "shipping_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "units": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "units_sub": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "materiels": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouse_locations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "product_warehouse_locations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "show_product_gtin": {},
                                        "show_serial_tracking": {},
                                        "enable_multi_pack_selling": {},
                                        "enable_wholesale_pricing": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/products_clean_names": {
            "get": {
                "operationId": "get_api_products_clean_names",
                "tags": [
                    "Health & Utilities"
                ],
                "summary": "Strip `<` and `>` from product names",
                "description": "One-off maintenance helper: replaces `<` and `>` characters in every product name (they break receipt printing and are blocked by the request-safety filter). Returns how many products were changed. Public and idempotent; safe to call repeatedly.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "ProductsController@cleanNames",
                "x-source": "app/Http/Controllers/ProductsController.php#L4457-L4475",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Product"
                ],
                "responses": {
                    "200": {
                        "description": "Count of cleaned products in `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Cleaned {$count} products containing < or >."
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "message": "Cleaned 3 products containing < or >."
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/project_milestones": {
            "get": {
                "operationId": "get_api_project_milestones",
                "tags": [
                    "Project Milestones"
                ],
                "summary": "List milestones",
                "description": "Paginated milestones with their project, sorted by `due_date asc` then `position` by default. Sortable: `id, title, due_date, status, progress, position, created_at`. `search` matches the title.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectMilestoneController@index",
                "x-source": "app/Http/Controllers/ProjectMilestoneController.php#L19-L48",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ProjectMilestonePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProjectMilestone"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "overdue",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = only open milestones past their due date."
                    },
                    {
                        "name": "project_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Project filter."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`milestones[]` (with `days_to_due`, `is_overdue`) and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "milestones": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_project_milestones",
                "tags": [
                    "Project Milestones"
                ],
                "summary": "Create a milestone",
                "description": "Creates a milestone on a project (name, due date, description, order).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectMilestoneController@store",
                "x-source": "app/Http/Controllers/ProjectMilestoneController.php#L50-L61",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ProjectMilestonePolicy"
                    }
                ],
                "x-models": [
                    "ProjectMilestone"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "budget": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Budget amount."
                                    },
                                    "completed_on": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Completion date (defaults to today when status is completed)."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "position": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 9999,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:9999"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Manual order 0–9999."
                                    },
                                    "progress": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "0–100 (forced to 100 when completed, capped at 99 otherwise)."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "projects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:projects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "in_progress",
                                            "completed",
                                            "delayed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:pending,in_progress,completed,delayed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`pending`, `in_progress`, `completed`, `delayed`."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 191)."
                                    }
                                },
                                "required": [
                                    "project_id",
                                    "status",
                                    "title"
                                ]
                            },
                            "example": {
                                "project_id": 3,
                                "title": "Racking installed",
                                "due_date": "2026-10-15",
                                "status": "in_progress",
                                "progress": 40,
                                "budget": 12000,
                                "position": 2
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/project_milestones/delete/by_selection": {
            "post": {
                "operationId": "post_api_project_milestones_delete_by_selection",
                "tags": [
                    "Project Milestones"
                ],
                "summary": "Delete selected milestones",
                "description": "Bulk delete of milestones by `selectedIds`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectMilestoneController@deleteBySelection",
                "x-source": "app/Http/Controllers/ProjectMilestoneController.php#L99-L107",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ProjectMilestonePolicy"
                    }
                ],
                "x-models": [
                    "ProjectMilestone"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Milestone ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/project_milestones/{id}": {
            "delete": {
                "operationId": "delete_api_project_milestones_id",
                "tags": [
                    "Project Milestones"
                ],
                "summary": "Delete a milestone",
                "description": "Deletes a milestone; tasks linked to it are unlinked.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectMilestoneController@destroy",
                "x-source": "app/Http/Controllers/ProjectMilestoneController.php#L90-L97",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ProjectMilestonePolicy"
                    }
                ],
                "x-models": [
                    "ProjectMilestone"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Milestone id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_project_milestones_id",
                "tags": [
                    "Project Milestones"
                ],
                "summary": "Update a milestone",
                "description": "Updates a milestone (name, due date, status, order).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectMilestoneController@update",
                "x-source": "app/Http/Controllers/ProjectMilestoneController.php#L63-L71",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ProjectMilestonePolicy"
                    }
                ],
                "x-models": [
                    "ProjectMilestone"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Milestone id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "budget": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Budget."
                                    },
                                    "completed_on": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Completion date."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "position": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 9999,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:9999"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Order."
                                    },
                                    "progress": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Progress."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "projects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:projects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "in_progress",
                                            "completed",
                                            "delayed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:pending,in_progress,completed,delayed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "project_id",
                                    "status",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/project_milestones/{id}/status": {
            "post": {
                "operationId": "post_api_project_milestones_id_status",
                "tags": [
                    "Project Milestones"
                ],
                "summary": "Quick status change",
                "description": "Sets the status from the list without opening the form; applies the same completion rules.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectMilestoneController@setStatus",
                "x-source": "app/Http/Controllers/ProjectMilestoneController.php#L74-L88",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ProjectMilestonePolicy"
                    }
                ],
                "x-models": [
                    "ProjectMilestone"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Milestone id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "in_progress",
                                            "completed",
                                            "delayed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:pending,in_progress,completed,delayed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New status."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and resulting `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/project_time_logs": {
            "get": {
                "operationId": "get_api_project_time_logs",
                "tags": [
                    "Project Time Logs"
                ],
                "summary": "List time logs",
                "description": "Paginated logs with project, task and employee, newest `log_date` first (sortable: `id, log_date, hours, amount, created_at`). `search` matches the description. `totals` sums hours and amount over the whole filtered set.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectTimeLogController@index",
                "x-source": "app/Http/Controllers/ProjectTimeLogController.php#L19-L71",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ProjectTimeLogPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProjectTimeLog"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "billable",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` billable only, `0` non-billable only."
                    },
                    {
                        "name": "employee_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Employee filter."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Log date to."
                    },
                    {
                        "name": "project_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Project filter."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Log date from."
                    },
                    {
                        "name": "task_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Task filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`time_logs[]`, `totalRows`, `totals{hours, amount}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "time_logs": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_project_time_logs",
                "tags": [
                    "Project Time Logs"
                ],
                "summary": "Log time",
                "description": "`amount` is computed as `hours × hourly_rate` when `billable` is true, otherwise 0.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectTimeLogController@store",
                "x-source": "app/Http/Controllers/ProjectTimeLogController.php#L73-L84",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ProjectTimeLogPolicy"
                    }
                ],
                "x-models": [
                    "ProjectTimeLog"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "billable": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Billable flag.",
                                        "type": "boolean"
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "What was done."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee (optional)."
                                    },
                                    "hourly_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rate used for the amount."
                                    },
                                    "hours": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "maximum": 24,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01",
                                            "max:24"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Hours worked (0.01–24)."
                                    },
                                    "log_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date of the work."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "projects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:projects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "task_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "tasks,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:tasks,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Task (optional)."
                                    }
                                },
                                "required": [
                                    "hours",
                                    "log_date",
                                    "project_id"
                                ]
                            },
                            "example": {
                                "project_id": 3,
                                "task_id": 12,
                                "employee_id": 7,
                                "log_date": "2026-09-05",
                                "hours": 6.5,
                                "billable": true,
                                "hourly_rate": 40,
                                "description": "Racking assembly"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "project_id": {},
                                        "task_id": {},
                                        "employee_id": {},
                                        "log_date": {},
                                        "hours": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "billable": {},
                                        "hourly_rate": {},
                                        "amount": {
                                            "type": "number"
                                        },
                                        "description": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/project_time_logs/delete/by_selection": {
            "post": {
                "operationId": "post_api_project_time_logs_delete_by_selection",
                "tags": [
                    "Project Time Logs"
                ],
                "summary": "Delete selected time logs",
                "description": "Bulk delete of time logs by `selectedIds`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectTimeLogController@deleteBySelection",
                "x-source": "app/Http/Controllers/ProjectTimeLogController.php#L105-L113",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ProjectTimeLogPolicy"
                    }
                ],
                "x-models": [
                    "ProjectTimeLog"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Time log ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/project_time_logs/{id}": {
            "delete": {
                "operationId": "delete_api_project_time_logs_id",
                "tags": [
                    "Project Time Logs"
                ],
                "summary": "Delete a time log",
                "description": "Deletes a time log entry.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectTimeLogController@destroy",
                "x-source": "app/Http/Controllers/ProjectTimeLogController.php#L96-L103",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ProjectTimeLogPolicy"
                    }
                ],
                "x-models": [
                    "ProjectTimeLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Time log id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_project_time_logs_id",
                "tags": [
                    "Project Time Logs"
                ],
                "summary": "Update a time log",
                "description": "Updates a time log (task, date, hours, billable flag, note).",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectTimeLogController@update",
                "x-source": "app/Http/Controllers/ProjectTimeLogController.php#L86-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ProjectTimeLogPolicy"
                    }
                ],
                "x-models": [
                    "ProjectTimeLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Time log id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "billable": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Billable flag.",
                                        "type": "boolean"
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "hourly_rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rate."
                                    },
                                    "hours": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "maximum": 24,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01",
                                            "max:24"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Hours."
                                    },
                                    "log_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "projects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:projects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "task_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "tasks,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:tasks,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Task."
                                    }
                                },
                                "required": [
                                    "hours",
                                    "log_date",
                                    "project_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "project_id": {},
                                        "task_id": {},
                                        "employee_id": {},
                                        "log_date": {},
                                        "hours": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "billable": {},
                                        "hourly_rate": {},
                                        "amount": {
                                            "type": "number"
                                        },
                                        "description": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects": {
            "get": {
                "operationId": "get_api_projects",
                "tags": [
                    "Projects"
                ],
                "summary": "List projects",
                "description": "Paginated projects with company / client names plus the per-status counters (`count_not_started`, `count_in_progress`, `count_completed`, `count_cancelled`) and the `companies` / `clients` lookups. `search` matches the title.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@index",
                "x-source": "app/Http/Controllers/ProjectController.php#L22-L126",
                "x-route-name": "projects.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "status",
                    "client_id",
                    "start_date",
                    "end_date",
                    "company_id"
                ],
                "x-models": [
                    "Project",
                    "Company",
                    "Client"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Client filter."
                    },
                    {
                        "name": "company_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Company filter."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact end date."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact start date."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter (LIKE) on status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`projects[]`, `totalRows`, `companies[]`, `clients[]`, counters.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count_not_started": {},
                                        "count_in_progress": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count_cancelled": {},
                                        "count_completed": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_projects",
                "tags": [
                    "Projects"
                ],
                "summary": "Create a project",
                "description": "Store a newly created resource in storage. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@store",
                "x-source": "app/Http/Controllers/ProjectController.php#L152-L180",
                "x-route-name": "projects.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Project"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee ids assigned to the project.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "client": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Client **id**.",
                                        "type": "integer"
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End date."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start date."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`not_started`, `progress`, `on_hold`, `completed`, `cancelled`."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 255)."
                                    }
                                },
                                "required": [
                                    "assigned_to",
                                    "client",
                                    "company_id",
                                    "end_date",
                                    "start_date",
                                    "status",
                                    "title"
                                ]
                            },
                            "example": {
                                "title": "Warehouse relocation",
                                "client": 4,
                                "company_id": 1,
                                "assigned_to": [
                                    7,
                                    9
                                ],
                                "start_date": "2026-09-01",
                                "end_date": "2026-11-30",
                                "status": "not_started",
                                "description": "Move stock to the new site."
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects/create": {
            "get": {
                "operationId": "get_api_projects_create",
                "tags": [
                    "Projects"
                ],
                "summary": "Create-form data for a project",
                "description": "Show the form for creating a new resource. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@create",
                "x-source": "app/Http/Controllers/ProjectController.php#L133-L145",
                "x-route-name": "projects.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`clients[]` and `companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects/dashboard": {
            "get": {
                "operationId": "get_api_projects_dashboard",
                "tags": [
                    "Project Workspace"
                ],
                "summary": "Project workspace dashboard",
                "description": "KPIs: `projects_total`, `projects_by_status[]`, `projects_open` (not_started/progress/on_hold), `projects_overdue`, `tasks_total`, `tasks_by_status[]`, `tasks_done`, `tasks_completion` (%), `tasks_overdue`, `milestones_open`, `milestones_overdue`, `hours_month`, `billable_month`, a 30-day `hours_trend`, `upcoming_milestones`, `active_projects` (8 soonest-ending) and per-employee `workload`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectWorkspaceController@dashboard",
                "x-source": "app/Http/Controllers/ProjectWorkspaceController.php#L33-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Project",
                    "Task",
                    "ProjectMilestone",
                    "ProjectTimeLog"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "projects_total": {
                                            "type": "integer"
                                        },
                                        "projects_by_status": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "projects_open": {
                                            "type": "integer"
                                        },
                                        "projects_overdue": {
                                            "type": "integer"
                                        },
                                        "tasks_total": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "tasks_by_status": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "tasks_done": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "tasks_completion": {
                                            "type": "number"
                                        },
                                        "tasks_overdue": {
                                            "type": "integer"
                                        },
                                        "milestones_open": {
                                            "type": "integer"
                                        },
                                        "milestones_overdue": {
                                            "type": "integer"
                                        },
                                        "hours_month": {
                                            "type": "number"
                                        },
                                        "billable_month": {
                                            "type": "number"
                                        },
                                        "hours_trend": {},
                                        "upcoming_milestones": {},
                                        "active_projects": {},
                                        "workload": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects/meta": {
            "get": {
                "operationId": "get_api_projects_meta",
                "tags": [
                    "Project Workspace"
                ],
                "summary": "Workspace form lookups",
                "description": "`projects` (id, title, status, client_id), `tasks` (id, title, project_id, status), `employees` (id, name) and `clients` (id, name) in one call.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectWorkspaceController@meta",
                "x-source": "app/Http/Controllers/ProjectWorkspaceController.php#L201-L215",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Project",
                    "Task",
                    "Employee",
                    "Client"
                ],
                "responses": {
                    "200": {
                        "description": "`projects[]`, `tasks[]`, `employees[]`, `clients[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "tasks": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects/reports/delivery": {
            "get": {
                "operationId": "get_api_projects_reports_delivery",
                "tags": [
                    "Project Workspace"
                ],
                "summary": "Delivery report (per project)",
                "description": "One row per project: task counts by status, progress %, estimated vs logged hours, billed amount, milestone completion and whether the project is late. Time-log hours are restricted to the `start_date`..`end_date` window when given. Paginated with `totals`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectWorkspaceController@projectReport",
                "x-source": "app/Http/Controllers/ProjectWorkspaceController.php#L222-L283",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "project_reports",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Project",
                    "Task",
                    "ProjectTimeLog",
                    "ProjectMilestone"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Client filter."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Hours window to."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Hours window from."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Project status filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects/reports/milestones": {
            "get": {
                "operationId": "get_api_projects_reports_milestones",
                "tags": [
                    "Project Workspace"
                ],
                "summary": "Milestone report",
                "description": "Every milestone with `days_to_due`, `is_overdue` and `slippage` (days late, negative = early, null while open). Paginated with totals.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectWorkspaceController@milestoneReport",
                "x-source": "app/Http/Controllers/ProjectWorkspaceController.php#L341-L374",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "project_reports",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProjectMilestone"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "project_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Project filter."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects/reports/workload": {
            "get": {
                "operationId": "get_api_projects_reports_workload",
                "tags": [
                    "Project Workspace"
                ],
                "summary": "Workload report (per employee)",
                "description": "Hours, billable hours and billable amount per employee for the period, sorted by hours. `search` matches employee name.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectWorkspaceController@workloadReport",
                "x-source": "app/Http/Controllers/ProjectWorkspaceController.php#L286-L338",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "project_reports",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProjectTimeLog",
                    "Employee"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "project_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Restrict to one project."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals{hours, billable_amount}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/projects/{project}": {
            "delete": {
                "operationId": "delete_api_projects_project",
                "tags": [
                    "Projects"
                ],
                "summary": "Delete a project",
                "description": "Soft-deletes the project.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@destroy",
                "x-source": "app/Http/Controllers/ProjectController.php#L260-L270",
                "x-route-name": "projects.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Project"
                ],
                "parameters": [
                    {
                        "name": "project",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Project id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_projects_project",
                "tags": [
                    "Projects"
                ],
                "summary": "Get a project (not implemented)",
                "description": "**Not implemented** — empty response; use the edit endpoint.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@show",
                "x-source": "app/Http/Controllers/ProjectController.php#L188-L191",
                "x-route-name": "projects.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "project",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Project id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_projects_project",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Projects"
                ],
                "summary": "Update a project",
                "description": "Full update; `assigned_to` replaces the assignment list.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@update",
                "x-source": "app/Http/Controllers/ProjectController.php#L224-L252",
                "x-route-name": "projects.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Project"
                ],
                "parameters": [
                    {
                        "name": "project",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Project id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "client": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Client id.",
                                        "type": "integer"
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "assigned_to",
                                    "client",
                                    "company_id",
                                    "end_date",
                                    "start_date",
                                    "status",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_projects_project",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Projects"
                ],
                "summary": "Update a project",
                "description": "Full update; `assigned_to` replaces the assignment list.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@update",
                "x-source": "app/Http/Controllers/ProjectController.php#L224-L252",
                "x-route-name": "projects.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Project"
                ],
                "parameters": [
                    {
                        "name": "project",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Project id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employee ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "client": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Client id.",
                                        "type": "integer"
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company id."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "assigned_to",
                                    "client",
                                    "company_id",
                                    "end_date",
                                    "start_date",
                                    "status",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/projects/{project}/edit": {
            "get": {
                "operationId": "get_api_projects_project_edit",
                "tags": [
                    "Projects"
                ],
                "summary": "Edit-form data for a project",
                "description": "The `project`, its `assigned_employees` ids and the `companies`, `clients`, `employees` (of the project's company) lookups.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "ProjectController@edit",
                "x-source": "app/Http/Controllers/ProjectController.php#L199-L216",
                "x-route-name": "projects.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "projects",
                        "policy": "ProjectPolicy"
                    }
                ],
                "x-models": [
                    "Project",
                    "EmployeeProject",
                    "Client",
                    "Company",
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "project",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Project id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`project`, `assigned_employees[]`, `companies[]`, `clients[]`, `employees[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "project": {},
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "assigned_employees": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions": {
            "get": {
                "operationId": "get_api_promotions",
                "tags": [
                    "Promotions"
                ],
                "summary": "List promotions",
                "description": "Paginated promotions with their `warehouses` (`id, name`) and `products` (`id, name, code`). `search` matches name, code and description. Sortable by `id, name, kind, discount_type, discount_value, is_active, priority, starts_at, ends_at`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@index",
                "x-source": "app/Http/Controllers/PromotionsController.php#L18-L66",
                "x-route-name": "promotions.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Promotion"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`true`/`false` to filter on `is_active`."
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`discount` or `promotion`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only promotions attached to this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`promotions[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "promotions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_promotions",
                "tags": [
                    "Promotions"
                ],
                "summary": "Create a promotion",
                "description": "Creates a promotion and attaches warehouses and (when `product_scope = specific`) products. Returns HTTP **201**. Defaults: `is_active true`, `product_scope all`, `priority 0`, `stackable false`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@store",
                "x-source": "app/Http/Controllers/PromotionsController.php#L77-L119",
                "x-route-name": "promotions.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "Promotion"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Optional code the cashier/customer must enter to unlock it (max 64). Without a code the promotion applies automatically."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Internal description."
                                    },
                                    "discount_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:percentage,fixed"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`percentage` or `fixed`."
                                    },
                                    "discount_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Percent or amount, `>= 0`."
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Last valid date; must be `>= starts_at`."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable/disable."
                                    },
                                    "kind": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "discount",
                                            "promotion"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:discount,promotion"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`discount` or `promotion`."
                                    },
                                    "min_cart_total": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Minimum cart subtotal required."
                                    },
                                    "min_item_count": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Minimum number of items required."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Display name, max 192."
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Higher priority is evaluated first when several promotions match."
                                    },
                                    "product_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product ids the promotion applies to (specific scope).",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "product_scope": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "specific"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:all,specific"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`all` or `specific` (then send `product_ids`)."
                                    },
                                    "stackable": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`true` lets it combine with other promotions."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "First valid date (`YYYY-MM-DD`)."
                                    },
                                    "time_of_day_end": {
                                        "type": "string",
                                        "x-format": "date (H:i:s)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i:s"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Daily window end `HH:MM:SS`."
                                    },
                                    "time_of_day_start": {
                                        "type": "string",
                                        "x-format": "date (H:i:s)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i:s"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Daily window start `HH:MM:SS` (happy hour)."
                                    },
                                    "usage_limit_per_customer": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Maximum uses per customer."
                                    },
                                    "usage_limit_total": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Maximum number of uses overall."
                                    },
                                    "warehouse_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouses where it applies; empty = everywhere.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "required": [
                                    "discount_type",
                                    "discount_value",
                                    "kind",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Summer 10%",
                                "kind": "discount",
                                "discount_type": "percentage",
                                "discount_value": 10,
                                "starts_at": "2026-06-01",
                                "ends_at": "2026-08-31",
                                "min_cart_total": 50,
                                "product_scope": "all",
                                "warehouse_ids": [
                                    1
                                ],
                                "is_active": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and the created `promotion` with relations.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "promotion": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions/applicable": {
            "post": {
                "operationId": "post_api_promotions_applicable",
                "tags": [
                    "Promotions"
                ],
                "summary": "Find promotions applicable to a cart",
                "description": "Runs the promotion engine on a cart context and returns the promotions that currently apply with the computed discount, so POS can show eligible deals before checkout. Send `code` to unlock code-gated promotions and `client_id` so per-customer caps are enforced.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@applicable",
                "x-source": "app/Http/Controllers/PromotionsController.php#L218-L247",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id for per-customer usage caps."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Promotion code typed by the cashier."
                                    },
                                    "item_count": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Number of items in the cart."
                                    },
                                    "product_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Product ids in the cart.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "product_subtotals": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "product_id": {
                                                    "type": "integer",
                                                    "x-conditional": [
                                                        "required_with:product_subtotals"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:product_subtotals",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product id."
                                                },
                                                "subtotal": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "x-conditional": [
                                                        "required_with:product_subtotals"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:product_subtotals",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Subtotal for that product."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Per-product subtotals for product-scoped promotions."
                                    },
                                    "subtotal": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cart subtotal before discounts."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse of the sale."
                                    }
                                },
                                "required": [
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "warehouse_id": 1,
                                "subtotal": 120,
                                "item_count": 3,
                                "product_ids": [
                                    5,
                                    9
                                ],
                                "client_id": 3
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Engine result: applicable promotions with per-promotion `discount_amount`, total discount and skipped promotions with reasons.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions/preview_warehouses": {
            "post": {
                "operationId": "post_api_promotions_preview_warehouses",
                "tags": [
                    "Promotions"
                ],
                "summary": "Resolve warehouse names",
                "description": "Returns `{id, name}` for the given warehouse ids — used by the form to preview where a promotion will apply before saving.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@previewWarehouses",
                "x-source": "app/Http/Controllers/PromotionsController.php#L197-L208",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "warehouse_ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of warehouse ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions/usages": {
            "get": {
                "operationId": "get_api_promotions_usages",
                "tags": [
                    "Promotions"
                ],
                "summary": "List promotion usages",
                "description": "Paginated log of every promotion application. Rows: `id, used_at, discount_amount, code, promotion {id, name, code, kind, discount_type, discount_value}, sale {id, Ref}, client {id, name}, warehouse {id, name}`. `search` matches the code, promotion name/code, sale Ref or customer name. Sortable by `id, used_at, discount_amount, promotion_id, sale_id, client_id, warehouse_id`. Default 15 rows per page.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@usages",
                "x-source": "app/Http/Controllers/PromotionsController.php#L292-L379",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PromotionUsage",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this customer."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start of `used_at` range (`YYYY-MM-DD`)."
                    },
                    {
                        "name": "promotion_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this promotion."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End of `used_at` range (inclusive)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`usages[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "used_at": {
                                            "type": "string"
                                        },
                                        "discount_amount": {
                                            "type": "number"
                                        },
                                        "code": {},
                                        "promotion": {
                                            "type": "object"
                                        },
                                        "sale": {
                                            "type": "object"
                                        },
                                        "client": {
                                            "type": "object"
                                        },
                                        "warehouse": {
                                            "type": "object"
                                        },
                                        "usages": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions/usages_summary": {
            "get": {
                "operationId": "get_api_promotions_usages_summary",
                "tags": [
                    "Promotions"
                ],
                "summary": "Get promotion usage totals",
                "description": "Aggregates usages per promotion within the optional filter window: `summary[]` rows with `promotion_id, name, code, kind, uses, unique_customers, total_discount, usage_limit_total` ordered by discount given, and `totals` (`uses`, `total_discount`, `promotions_with_usage`).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@usageSummary",
                "x-source": "app/Http/Controllers/PromotionsController.php#L386-L439",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "PromotionUsage",
                    "Promotion"
                ],
                "parameters": [
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this customer."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (inclusive)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`summary[]` and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "promotion_id": {
                                            "type": "integer"
                                        },
                                        "name": {},
                                        "code": {},
                                        "kind": {},
                                        "uses": {
                                            "type": "integer"
                                        },
                                        "unique_customers": {
                                            "type": "integer"
                                        },
                                        "total_discount": {
                                            "type": "number"
                                        },
                                        "usage_limit_total": {
                                            "type": "integer"
                                        },
                                        "summary": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions/validate_code": {
            "post": {
                "operationId": "post_api_promotions_validate_code",
                "tags": [
                    "Promotions"
                ],
                "summary": "Validate a promotion code",
                "description": "Checks one code against the current context and returns `ok` with a machine-readable `reason` when it cannot be used (`not_found`, `inactive`, `expired`, `not_started`, `exhausted`, `customer_limit`, `wrong_warehouse`, …) plus a summary of the matched `promotion`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@validateCode",
                "x-source": "app/Http/Controllers/PromotionsController.php#L254-L281",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id for per-customer caps."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Promotion code."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse of the sale."
                                    }
                                },
                                "required": [
                                    "code",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `reason`, `promotion` (or `null`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {},
                                        "reason": {},
                                        "promotion": {
                                            "type": "object"
                                        }
                                    }
                                },
                                "example": {
                                    "ok": true,
                                    "reason": null,
                                    "promotion": {
                                        "id": 4,
                                        "name": "WELCOME10",
                                        "kind": "discount",
                                        "discount_type": "percentage",
                                        "discount_value": 10
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions/{id}/toggle": {
            "post": {
                "operationId": "post_api_promotions_id_toggle",
                "tags": [
                    "Promotions"
                ],
                "summary": "Toggle a promotion on/off",
                "description": "Flips `is_active` and returns the new value.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@toggle",
                "x-source": "app/Http/Controllers/PromotionsController.php#L178-L190",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "Promotion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Promotion id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and new `is_active`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "is_active": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "is_active": false
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/promotions/{promotion}": {
            "delete": {
                "operationId": "delete_api_promotions_promotion",
                "tags": [
                    "Promotions"
                ],
                "summary": "Delete a promotion",
                "description": "Deletes the promotion (usage history is kept).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@destroy",
                "x-source": "app/Http/Controllers/PromotionsController.php#L165-L173",
                "x-route-name": "promotions.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "Promotion"
                ],
                "parameters": [
                    {
                        "name": "promotion",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Promotion id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_promotions_promotion",
                "tags": [
                    "Promotions"
                ],
                "summary": "Get a promotion",
                "description": "One promotion with its `warehouses` and `products`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@show",
                "x-source": "app/Http/Controllers/PromotionsController.php#L68-L75",
                "x-route-name": "promotions.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "Promotion"
                ],
                "parameters": [
                    {
                        "name": "promotion",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Promotion id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`promotion` object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "promotion": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_promotions_promotion",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Promotions"
                ],
                "summary": "Update a promotion",
                "description": "Replaces all attributes; warehouses and products are re-synced (products are cleared when `product_scope` is `all`). Omitting `is_active` keeps the current value.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@update",
                "x-source": "app/Http/Controllers/PromotionsController.php#L121-L163",
                "x-route-name": "promotions.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "Promotion"
                ],
                "parameters": [
                    {
                        "name": "promotion",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Promotion id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Code."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "discount_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:percentage,fixed"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`percentage`/`fixed`."
                                    },
                                    "discount_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Value."
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "End date."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "kind": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "discount",
                                            "promotion"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:discount,promotion"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`discount`/`promotion`."
                                    },
                                    "min_cart_total": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Min subtotal."
                                    },
                                    "min_item_count": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Min items."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Priority."
                                    },
                                    "product_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "product_scope": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "specific"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:all,specific"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`all`/`specific`."
                                    },
                                    "stackable": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Stackable flag."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Start date."
                                    },
                                    "time_of_day_end": {
                                        "type": "string",
                                        "x-format": "date (H:i:s)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i:s"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Window end."
                                    },
                                    "time_of_day_start": {
                                        "type": "string",
                                        "x-format": "date (H:i:s)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i:s"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Window start."
                                    },
                                    "usage_limit_per_customer": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-customer cap."
                                    },
                                    "usage_limit_total": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Total cap."
                                    },
                                    "warehouse_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "required": [
                                    "discount_type",
                                    "discount_value",
                                    "kind",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the updated `promotion`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "promotion": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_promotions_promotion",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Promotions"
                ],
                "summary": "Update a promotion",
                "description": "Replaces all attributes; warehouses and products are re-synced (products are cleared when `product_scope` is `all`). Omitting `is_active` keeps the current value.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "PromotionsController@update",
                "x-source": "app/Http/Controllers/PromotionsController.php#L121-L163",
                "x-route-name": "promotions.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "promotion",
                        "policy": "PromotionPolicy"
                    }
                ],
                "x-models": [
                    "Promotion"
                ],
                "parameters": [
                    {
                        "name": "promotion",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Promotion id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Code."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "discount_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:percentage,fixed"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`percentage`/`fixed`."
                                    },
                                    "discount_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Value."
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "End date."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "kind": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "discount",
                                            "promotion"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:discount,promotion"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`discount`/`promotion`."
                                    },
                                    "min_cart_total": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Min subtotal."
                                    },
                                    "min_item_count": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Min items."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Priority."
                                    },
                                    "product_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "product_scope": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "specific"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:all,specific"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`all`/`specific`."
                                    },
                                    "stackable": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Stackable flag."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Start date."
                                    },
                                    "time_of_day_end": {
                                        "type": "string",
                                        "x-format": "date (H:i:s)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i:s"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Window end."
                                    },
                                    "time_of_day_start": {
                                        "type": "string",
                                        "x-format": "date (H:i:s)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i:s"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Window start."
                                    },
                                    "usage_limit_per_customer": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-customer cap."
                                    },
                                    "usage_limit_total": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Total cap."
                                    },
                                    "warehouse_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "required": [
                                    "discount_type",
                                    "discount_value",
                                    "kind",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the updated `promotion`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "promotion": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/provider_details/payments": {
            "get": {
                "operationId": "get_api_provider_details_payments",
                "tags": [
                    "Suppliers"
                ],
                "summary": "List a supplier's payments (ledger)",
                "description": "Paginated purchase payments for one supplier, newest first. Rows: `date, Ref, purchase_Ref, payment_method, montant`. Same record-view / warehouse scoping as the purchases list.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@supplierPayments",
                "x-source": "app/Http/Controllers/ProvidersController.php#L353-L403",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Suppliers_view",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier id (query string)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/provider_details/purchases": {
            "get": {
                "operationId": "get_api_provider_details_purchases",
                "tags": [
                    "Suppliers"
                ],
                "summary": "List a supplier's purchases (ledger)",
                "description": "Paginated purchases for one supplier, newest first. Rows: `id, Ref, warehouse_name, provider_name, statut, GrandTotal, paid_amount, due, payment_status`. Results are scoped by the caller's **record view** setting (own documents only unless the user may view all records) and by their assigned warehouses. `search` matches `Ref`, `statut`, `payment_statut`, supplier and warehouse names.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@supplierPurchases",
                "x-source": "app/Http/Controllers/ProvidersController.php#L281-L350",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Suppliers_view",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Purchase"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier id (query string)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchases[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/provider_details/returns": {
            "get": {
                "operationId": "get_api_provider_details_returns",
                "tags": [
                    "Suppliers"
                ],
                "summary": "List a supplier's purchase returns (ledger)",
                "description": "Paginated purchase returns for one supplier, newest first. Rows: `id, Ref, statut, purchase_ref, warehouse_name, provider_name, GrandTotal, paid_amount, due, payment_status`. Same record-view / warehouse scoping as the purchases list.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@supplierReturns",
                "x-source": "app/Http/Controllers/ProvidersController.php#L406-L482",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Suppliers_view",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PurchaseReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier id (query string)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`returns_supplier[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "returns_supplier": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/provider_details/summary/{id}": {
            "get": {
                "operationId": "get_api_provider_details_summary_id",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Get supplier summary (ledger header)",
                "description": "Totals for the supplier details page: `report.total_purchase` (count of purchases), `total_amount` (received purchases), `total_paid`, `due`, `opening_balance`, `credit_limit`, `name`, `return_Due` (purchase returns not yet refunded). Also returns `accounts` and `payment_methods` for the pay-due dialogs.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@supplierDetailsSummary",
                "x-source": "app/Http/Controllers/ProvidersController.php#L234-L278",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Suppliers_view",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider",
                    "Account",
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Supplier id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`report` totals plus lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "report": {
                                        "total_purchase": 14,
                                        "total_amount": 12000,
                                        "total_paid": 9000,
                                        "due": 3000,
                                        "opening_balance": 0,
                                        "credit_limit": 0,
                                        "name": "Global Parts SA",
                                        "return_Due": 0
                                    },
                                    "accounts": [
                                        {
                                            "id": 1,
                                            "account_name": "Main cash"
                                        }
                                    ],
                                    "payment_methods": [
                                        {
                                            "id": 1,
                                            "name": "Cash"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/providers": {
            "get": {
                "operationId": "get_api_providers",
                "tags": [
                    "Suppliers"
                ],
                "summary": "List suppliers",
                "description": "Paginated list of suppliers with their financial position. Each row adds `total_amount` (sum of **received** purchases), `total_paid`, `due`, and the purchase-return equivalents `total_amount_return`, `total_paid_return`, `return_Due` (what the supplier owes you back). Also returns `company_info`, `accounts` and `payment_methods` for the pay-due dialog.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@index",
                "x-source": "app/Http/Controllers/ProvidersController.php#L26-L118",
                "x-route-name": "providers.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Suppliers_view",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "name",
                    "code",
                    "phone",
                    "email"
                ],
                "x-models": [
                    "Provider",
                    "Setting",
                    "Account",
                    "PaymentMethod"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on supplier code."
                    },
                    {
                        "name": "email",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on email."
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on supplier name (`LIKE`)."
                    },
                    {
                        "name": "phone",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on phone."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`providers[]`, `totalRows`, `company_info`, `accounts`, `payment_methods`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "providers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "company_info": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "providers": [
                                        {
                                            "id": 2,
                                            "code": 2,
                                            "name": "Global Parts SA",
                                            "phone": "+33100000000",
                                            "email": "sales@globalparts.test",
                                            "adresse": "1 Rue X",
                                            "country": "FR",
                                            "city": "Lyon",
                                            "tax_number": "FR123",
                                            "opening_balance": 0,
                                            "credit_limit": 0,
                                            "total_amount": 12000,
                                            "total_paid": 9000,
                                            "due": 3000,
                                            "total_amount_return": 0,
                                            "total_paid_return": 0,
                                            "return_Due": 0
                                        }
                                    ],
                                    "totalRows": 1,
                                    "company_info": [],
                                    "accounts": [],
                                    "payment_methods": []
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_providers",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Create a supplier",
                "description": "Creates a supplier. `code` is generated automatically. Only `name` is validated; other fields are stored as sent. `opening_balance` and `credit_limit` default to `0`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@store",
                "x-source": "app/Http/Controllers/ProvidersController.php#L122-L148",
                "x-route-name": "providers.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Suppliers_add",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "adresse": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Street address."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "credit_limit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Credit limit granted by the supplier (informational)."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email address."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Supplier name. Required."
                                    },
                                    "opening_balance": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Amount you already owed this supplier before Stocky. Paid down first by *pay supplier due*."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number."
                                    },
                                    "tax_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax / VAT number."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Global Parts SA",
                                "email": "sales@globalparts.test",
                                "phone": "+33100000000",
                                "adresse": "1 Rue X",
                                "country": "FR",
                                "city": "Lyon",
                                "tax_number": "FR123",
                                "opening_balance": 0,
                                "credit_limit": 0
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, new `id` and the `provider` row.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "provider": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "id": 7,
                                    "provider": {
                                        "id": 7,
                                        "code": 7,
                                        "name": "Global Parts SA"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/providers/delete/by_selection": {
            "post": {
                "operationId": "post_api_providers_delete_by_selection",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Delete several suppliers",
                "description": "Soft-deletes each supplier id in `selectedIds`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@delete_by_selection",
                "x-source": "app/Http/Controllers/ProvidersController.php#L500-L513",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Suppliers_delete",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of supplier ids."
                                    }
                                }
                            },
                            "example": {
                                "selectedIds": [
                                    3,
                                    4
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/providers/{id}/adjust-opening-balance": {
            "post": {
                "operationId": "post_api_providers_id_adjust_opening_balance",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Adjust a supplier's opening balance",
                "description": "Changes the supplier's `opening_balance` without creating a payment. `mode=add` adds `|amount|`, `subtract` removes `|amount|`, `set` replaces the value. Rounded to 2 decimals.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@adjustOpeningBalance",
                "x-source": "app/Http/Controllers/ProvidersController.php#L192-L226",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Suppliers_edit",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Supplier id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount to apply."
                                    },
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "add",
                                            "subtract",
                                            "set"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:add,subtract,set"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`add`, `subtract` or `set`."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "mode"
                                ]
                            },
                            "example": {
                                "mode": "set",
                                "amount": 1500
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Previous and new opening balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "previous_opening_balance": {
                                            "type": "number"
                                        },
                                        "opening_balance": {
                                            "type": "number"
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "previous_opening_balance": 0,
                                    "opening_balance": 1500
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/providers/{provider}": {
            "delete": {
                "operationId": "delete_api_providers_provider",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Delete a supplier",
                "description": "Soft-deletes the supplier. Purchases referencing it are kept.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@destroy",
                "x-source": "app/Http/Controllers/ProvidersController.php#L486-L496",
                "x-route-name": "providers.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Suppliers_delete",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "parameters": [
                    {
                        "name": "provider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Supplier id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_providers_provider",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Get a supplier",
                "description": "Returns one supplier record. Soft-deleted suppliers return 404.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@show",
                "x-source": "app/Http/Controllers/ProvidersController.php#L152-L162",
                "x-route-name": "providers.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Suppliers_view",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "parameters": [
                    {
                        "name": "provider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Supplier id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`provider` object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "provider": {}
                                    }
                                },
                                "example": {
                                    "provider": {
                                        "id": 2,
                                        "code": 2,
                                        "name": "Global Parts SA",
                                        "email": "sales@globalparts.test",
                                        "phone": "+33100000000",
                                        "opening_balance": 0,
                                        "credit_limit": 0
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_providers_provider",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Suppliers"
                ],
                "summary": "Update a supplier",
                "description": "Replaces the supplier's contact fields and `credit_limit`. `opening_balance` is not editable here — use *Adjust opening balance*.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@update",
                "x-source": "app/Http/Controllers/ProvidersController.php#L166-L187",
                "x-route-name": "providers.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Suppliers_edit",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "parameters": [
                    {
                        "name": "provider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Supplier id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "adresse": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Street address."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "credit_limit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Credit limit (default `0` when omitted)."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email address."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Supplier name. Required."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number."
                                    },
                                    "tax_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax / VAT number."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Global Parts SA",
                                "email": "sales@globalparts.test",
                                "phone": "+33100000000",
                                "credit_limit": 10000
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_providers_provider",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Suppliers"
                ],
                "summary": "Update a supplier",
                "description": "Replaces the supplier's contact fields and `credit_limit`. `opening_balance` is not editable here — use *Adjust opening balance*.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@update",
                "x-source": "app/Http/Controllers/ProvidersController.php#L166-L187",
                "x-route-name": "providers.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Suppliers_edit",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "parameters": [
                    {
                        "name": "provider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Supplier id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "adresse": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Street address."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "credit_limit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Credit limit (default `0` when omitted)."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email address."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Supplier name. Required."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number."
                                    },
                                    "tax_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax / VAT number."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Global Parts SA",
                                "email": "sales@globalparts.test",
                                "phone": "+33100000000",
                                "credit_limit": 10000
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/purchase_pdf/{id}": {
            "get": {
                "operationId": "get_api_purchase_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Purchase order PDF",
                "description": "A4 purchase document following the `purchase` PDF template settings; includes batch numbers and expiry dates when present.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PurchasesController@Purchase_pdf",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1138-L1256",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Purchase",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file `Purchase_<Ref>.pdf`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/purchase_print_html/{id}": {
            "get": {
                "operationId": "get_api_purchase_print_html_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Purchase order HTML",
                "description": "Returns the purchase invoice HTML (rendered from pdf.purchase_pdf template) instead of a PDF. Uses the same template (`pdf.purchase_pdf`) but returns raw HTML instead of a PDF. This is used by the print functionality, which opens a popup, injects the HTML, and calls window.print(). /",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PurchasesController@Purchase_PDF_Inline",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1264-L1397",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Purchase",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "html",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "HTML document.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/purchase_send_email": {
            "post": {
                "operationId": "post_api_purchase_send_email",
                "tags": [
                    "Purchases"
                ],
                "summary": "Email the purchase order to the supplier",
                "description": "Sends the *purchase* email template to the supplier with `{contact_name}`, `{business_name}`, `{invoice_url}` (public PDF), `{invoice_number}`, `{total_amount}`, `{paid_amount}`, `{due_amount}`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@Send_Email",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1864-L1923",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchases_view",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "Setting",
                    "EmailMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchase_send_sms": {
            "post": {
                "operationId": "post_api_purchase_send_sms",
                "tags": [
                    "Purchases"
                ],
                "summary": "SMS the purchase order to the supplier",
                "description": "Sends the *purchase* SMS template through the default SMS gateway.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@Send_SMS",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1927-L2070",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchases_view",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "Setting",
                    "sms_gateway",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchase_send_whatsapp": {
            "post": {
                "operationId": "post_api_purchase_send_whatsapp",
                "tags": [
                    "Purchases"
                ],
                "summary": "Build a WhatsApp message for a purchase",
                "description": "Returns the rendered SMS template and the supplier's `phone`; nothing is sent server-side.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@purchase_send_whatsapp",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2073-L2127",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Purchase",
                    "Setting",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message` and `phone`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "phone": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Supplier has no phone.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Phone number is missing"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases": {
            "get": {
                "operationId": "get_api_purchases",
                "tags": [
                    "Purchases"
                ],
                "summary": "List purchases",
                "description": "Paginated purchases scoped to the caller's warehouses and record view. Rows: `id, date, Ref, created_by, statut, discount, shipping, GrandTotal, paid_amount, due, payment_status, warehouse_name, provider_id, provider_name, provider_email, provider_tele, provider_adr, currency_code, documents_count, purchase_has_return, purchasereturn_id`. `search` matches Ref, statut, exact GrandTotal, payment status, supplier and warehouse names. `stats` summarises the filtered set. Also returns `suppliers`, `warehouses`, `accounts`, `payment_methods`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@index",
                "x-source": "app/Http/Controllers/PurchasesController.php#L49-L210",
                "x-route-name": "purchases.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchases_view",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "statut",
                    "provider_id",
                    "payment_statut",
                    "warehouse_id",
                    "date"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Purchase",
                    "PurchaseReturn",
                    "Provider",
                    "Account",
                    "Warehouse",
                    "PaymentMethod"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact date."
                    },
                    {
                        "name": "payment_statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "`paid`, `partial`, `unpaid`."
                    },
                    {
                        "name": "provider_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Supplier id."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "`received`, `pending` or `ordered`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchases[]`, `totalRows`, `stats`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_purchases",
                "tags": [
                    "Purchases"
                ],
                "summary": "Create a purchase",
                "description": "Creates a purchase with its lines. When `statut` is `received`, each line's quantity (× purchase-unit operator) is **added** to the warehouse stock, batch rows are created for batch-tracked products from `batches[]`, and serial numbers listed in `imei_number` / `serials[]` are registered as available. Multi-currency: send `currency_id` and `exchange_rate` to snapshot a document currency.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@store",
                "x-source": "app/Http/Controllers/PurchasesController.php#L214-L329",
                "x-route-name": "purchases.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchases_add",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "Unit",
                    "product_warehouse",
                    "PurchaseDetail"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Purchase date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Lines: `{product_id, product_variant_id, quantity, purchase_unit_id, Unit_cost, tax_percent, tax_method, discount, discount_Method, subtotal, imei_number, batches?: [{batch_no, expiry_date, mfg_date, qty, unit_cost}]}`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount amount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping cost.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`received`, `pending` or `ordered`.",
                                        "type": "string"
                                    },
                                    "supplier_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Supplier id. Required."
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    },
                                    "currency_id": {
                                        "type": "integer",
                                        "description": "Document currency id (multi-currency).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "exchange_rate": {
                                        "type": "number",
                                        "description": "Exchange rate snapshot.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "supplier_id",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "supplier_id": 2,
                                "warehouse_id": 1,
                                "date": "2026-09-06",
                                "statut": "received",
                                "tax_rate": 0,
                                "TaxNet": 0,
                                "discount": 0,
                                "shipping": 0,
                                "GrandTotal": 850,
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 100,
                                        "purchase_unit_id": 1,
                                        "Unit_cost": 8.5,
                                        "tax_percent": 0,
                                        "tax_method": "1",
                                        "discount": 0,
                                        "discount_Method": "2",
                                        "subtotal": 850,
                                        "imei_number": null
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Purchase Created !!"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases/create": {
            "get": {
                "operationId": "get_api_purchases_create",
                "tags": [
                    "Purchases"
                ],
                "summary": "Get lookups for the purchase form",
                "description": "The caller's `warehouses` and all `suppliers` (`id, name`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@create",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1401-L1421",
                "x-route-name": "purchases.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchases_add",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Provider"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases/documents/{id}": {
            "delete": {
                "operationId": "delete_api_purchases_documents_id",
                "tags": [
                    "Purchases"
                ],
                "summary": "Delete a purchase document",
                "description": "Soft-deletes the document row and removes the file from disk.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@deleteDocument",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2536-L2567",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Purchases_delete",
                        "policy": "PurchasePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`status: true`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Document deleted successfully"
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases/documents/{id}/download": {
            "get": {
                "operationId": "get_api_purchases_documents_id_download",
                "tags": [
                    "Purchases"
                ],
                "summary": "Download a purchase document",
                "description": "Streams the stored file with its original name.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@downloadDocument",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2506-L2533",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchases_view",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases/{id}/barcodes": {
            "get": {
                "operationId": "get_api_purchases_id_barcodes",
                "tags": [
                    "Purchases"
                ],
                "summary": "Get label data for a purchase",
                "description": "For printing barcode labels of everything just received: `warehouse_id` and `products[]` (`code, name, barcode, quantity, price, price with tax/discount, product_id, variant`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@get_barcode_products",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1768-L1860",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchases_view",
                        "policy": "PurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`warehouse_id` and `products[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouse_id": {},
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases/{id}/documents": {
            "get": {
                "operationId": "get_api_purchases_id_documents",
                "tags": [
                    "Purchases"
                ],
                "summary": "List documents attached to a purchase",
                "description": "Files uploaded against the purchase (`id, name, path, size, mime_type, created_at`), newest first.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@getDocuments",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2433-L2449",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchases_view",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Purchase"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`documents[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_purchases_id_documents",
                "tags": [
                    "Purchases"
                ],
                "summary": "Upload documents to a purchase",
                "description": "Uploads one or more files (max 10 MB each) as `documents[]` into `/images/purchase_documents/`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@uploadDocuments",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2452-L2503",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Purchases_edit",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Purchase"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "documents": {
                                        "type": "array",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Array of files.",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "maxLength": 10240,
                                            "x-laravel-rules": [
                                                "required",
                                                "file",
                                                "max:10240"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`documents[]` (new ids).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Documents uploaded successfully"
                                        },
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases/{purchase}": {
            "delete": {
                "operationId": "delete_api_purchases_purchase",
                "tags": [
                    "Purchases"
                ],
                "summary": "Delete a purchase",
                "description": "Soft-deletes the purchase, its lines and payments (reverting account balances). Stock added by a `received` purchase is removed again; batches and serials are reversed. Purchases with a return cannot be deleted (`403`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@destroy",
                "x-source": "app/Http/Controllers/PurchasesController.php#L645-L778",
                "x-route-name": "purchases.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Purchases_delete",
                        "policy": "PurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "UserWarehouse",
                    "PurchaseDetail",
                    "PurchaseReturn",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "PaymentPurchase",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Purchase Deleted !!"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Return exists or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_purchases_purchase",
                "tags": [
                    "Purchases"
                ],
                "summary": "Get a purchase",
                "description": "Detail view: `purchase` header (`id, Ref, currency_*, date, statut, note, discount, shipping, tax_rate, TaxNet, supplier_* fields, warehouse, GrandTotal, paid_amount, due, payment_status, purchase_has_return, purchasereturn_id`), `details[]` lines (`code, name, quantity, unit, cost, discount, tax, total, imei_number, batches[] with batch_no/expiry_date/mfg_date/qty/unit_cost`) and `company`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@show",
                "x-source": "app/Http/Controllers/PurchasesController.php#L920-L1066",
                "x-route-name": "purchases.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchases_view",
                        "policy": "PurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "PurchaseReturn",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchase`, `details[]`, `company`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "batch_no": {},
                                        "expiry_date": {},
                                        "mfg_date": {},
                                        "qty": {},
                                        "unit_cost": {},
                                        "barcode": {},
                                        "notes": {},
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchase": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "company": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_purchases_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchases"
                ],
                "summary": "Update a purchase",
                "description": "Same payload as create. Stock added by the old `received` lines is reversed and the new lines applied; batches and serials are re-synced (serials only when the payload carries them). A purchase with a return cannot be edited (`403`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@update",
                "x-source": "app/Http/Controllers/PurchasesController.php#L354-L641",
                "x-route-name": "purchases.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Purchases_edit",
                        "policy": "PurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "UserWarehouse",
                    "PurchaseReturn",
                    "PurchaseDetail",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`received`/`pending`/`ordered`.",
                                        "type": "string"
                                    },
                                    "supplier_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Supplier id. Required."
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "supplier_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Purchase Updated !!"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Return exists or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_purchases_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchases"
                ],
                "summary": "Update a purchase",
                "description": "Same payload as create. Stock added by the old `received` lines is reversed and the new lines applied; batches and serials are re-synced (serials only when the payload carries them). A purchase with a return cannot be edited (`403`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@update",
                "x-source": "app/Http/Controllers/PurchasesController.php#L354-L641",
                "x-route-name": "purchases.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Purchases_edit",
                        "policy": "PurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "UserWarehouse",
                    "PurchaseReturn",
                    "PurchaseDetail",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`received`/`pending`/`ordered`.",
                                        "type": "string"
                                    },
                                    "supplier_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Supplier id. Required."
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "supplier_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Purchase Updated !!"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Return exists or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/purchases/{purchase}/edit": {
            "get": {
                "operationId": "get_api_purchases_purchase_edit",
                "tags": [
                    "Purchases"
                ],
                "summary": "Get a purchase for editing",
                "description": "Form-shaped payload: `purchase` (`supplier_id, warehouse_id, date, statut, tax_rate, TaxNet, discount, shipping, notes`), `details[]` lines (`id, detail_id, product_id, product_variant_id, code, name, quantity, purchase_unit_id, Unit_cost, Net_cost, tax_percent, tax_method, discount, discount_Method, subtotal, stock, imei_number, batches`) and the `suppliers` / `warehouses` lookups. A purchase with a return cannot be edited (`403`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@edit",
                "x-source": "app/Http/Controllers/PurchasesController.php#L1425-L1625",
                "x-route-name": "purchases.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Purchases_edit",
                        "policy": "PurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "Purchase",
                    "UserWarehouse",
                    "Provider",
                    "Warehouse",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchase`, `details[]`, `suppliers[]`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchase": {},
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Return exists or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/purchases_delete_by_selection": {
            "post": {
                "operationId": "post_api_purchases_delete_by_selection",
                "tags": [
                    "Purchases"
                ],
                "summary": "Delete several purchases",
                "description": "Deletes each purchase in `selectedIds` with the same rules; stops with `403` at the first one that has a return.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@delete_by_selection",
                "x-source": "app/Http/Controllers/PurchasesController.php#L782-L916",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Purchases_delete",
                        "policy": "PurchasePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "Purchase",
                    "UserWarehouse",
                    "PurchaseDetail",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "PaymentPurchase",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of purchase ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Purchase Deleted !!"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quickbooks/audits": {
            "get": {
                "operationId": "get_api_quickbooks_audits",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "QuickBooks audit log",
                "description": "Paginated audit trail of QuickBooks pushes: entity, Stocky ID, QuickBooks ID, action, status and error message.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@audits",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L332-L342",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "QuickBooksAudit"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Level filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator (25 per page).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quickbooks/clients-stats": {
            "get": {
                "operationId": "get_api_quickbooks_clients_stats",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "Customer sync statistics",
                "description": "Counts of customers synced vs not synced to QuickBooks.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@clientsStats",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L360-L373",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Client"
                ],
                "responses": {
                    "200": {
                        "description": "`total`, `synced`, `not_synced`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "synced": {},
                                        "not_synced": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quickbooks/clients-unsynced": {
            "get": {
                "operationId": "get_api_quickbooks_clients_unsynced",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "Unsynced customers",
                "description": "Customers that have no QuickBooks counterpart yet.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@clientsUnsynced",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L376-L403",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name or email."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`items[]`, `total`, `current_page`, `last_page`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "last_page": {
                                            "type": "integer"
                                        },
                                        "total": {
                                            "type": "integer"
                                        },
                                        "current_page": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quickbooks/disconnect": {
            "post": {
                "operationId": "post_api_quickbooks_disconnect",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "Disconnect QuickBooks",
                "description": "POST /quickbooks/disconnect (behind auth)",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@disconnect",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L239-L250",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "QuickBooksToken"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quickbooks/settings": {
            "get": {
                "operationId": "get_api_quickbooks_settings",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "Get QuickBooks settings",
                "description": "Values from `config/services.quickbooks` (env).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@quickbookgetSettings",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L253-L256",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Settings object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_quickbooks_settings",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "Save QuickBooks settings",
                "description": "Writes the values to `.env` and clears the config cache.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@saveSettings",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L259-L289",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "App client id."
                                    },
                                    "client_secret": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "App client secret."
                                    },
                                    "env": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "Development",
                                            "Production"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:Development,Production"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`Development` or `Production`."
                                    },
                                    "income_account_name": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Income account used for invoices."
                                    },
                                    "realm_id": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Company (realm) id."
                                    },
                                    "redirect": {
                                        "type": "string",
                                        "format": "uri",
                                        "x-laravel-rules": [
                                            "required",
                                            "url"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "OAuth redirect URI."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "client_secret",
                                    "env",
                                    "redirect"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quickbooks/status": {
            "get": {
                "operationId": "get_api_quickbooks_status",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "QuickBooks connection status",
                "description": "GET /quickbooks/status (behind auth)",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@status",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L220-L236",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "QuickBooksToken"
                ],
                "responses": {
                    "200": {
                        "description": "`env`, `redirect`, `callback`, `has_token`, `token_realm`, `updated_at`, `connect_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "env": {},
                                        "redirect": {},
                                        "callback": {
                                            "type": "string"
                                        },
                                        "has_token": {
                                            "type": "boolean"
                                        },
                                        "token_realm": {},
                                        "updated_at": {
                                            "type": "string"
                                        },
                                        "connect_url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quickbooks/sync-clients": {
            "post": {
                "operationId": "post_api_quickbooks_sync_clients",
                "tags": [
                    "QuickBooks"
                ],
                "summary": "Push customers to QuickBooks",
                "description": "Pushes unsynced customers (max 250 per call), optionally restricted to `ids`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "QuickBooksController@syncClients",
                "x-source": "app/Http/Controllers/QuickBooksController.php#L406-L468",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Client"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ids": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Customer ids to push.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `synced_count`, `failed_count`, `failures[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "synced_count": {},
                                        "failed_count": {
                                            "type": "integer"
                                        },
                                        "failures": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "note": {
                                            "type": "string",
                                            "example": "No unsynced clients found"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotation_send_whatsapp": {
            "post": {
                "operationId": "post_api_quotation_send_whatsapp",
                "tags": [
                    "Quotations"
                ],
                "summary": "Build a WhatsApp message for a quotation",
                "description": "Returns the rendered SMS template and the customer's `phone` for a `wa.me` link; nothing is sent server-side.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@quotation_send_whatsapp",
                "x-source": "app/Http/Controllers/QuotationsController.php#L1383-L1432",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Quotation",
                    "Setting",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Quotation id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message` and `phone`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "phone": {}
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Customer has no phone.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Phone number is missing"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotations": {
            "get": {
                "operationId": "get_api_quotations",
                "tags": [
                    "Quotations"
                ],
                "summary": "List quotations",
                "description": "Paginated quotations scoped to the caller's warehouses and record view. Rows: `id, date, Ref, client_name, warehouse_name, statut, GrandTotal, converted_sale_id, converted_sale_ref, created_by`. `search` matches Ref, statut, customer and warehouse names. `stats` summarises the filtered set. Also returns `customers` and `warehouses`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@index",
                "x-source": "app/Http/Controllers/QuotationsController.php#L44-L183",
                "x-route-name": "quotations.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Quotations_view",
                        "policy": "QuotationPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "statut",
                    "client_id",
                    "date",
                    "warehouse_id"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Quotation",
                    "Sale",
                    "Client",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Customer id."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact date."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "`pending` or `sent`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`quotations[]`, `totalRows`, `stats`, `customers[]`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "quotations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_quotations",
                "tags": [
                    "Quotations"
                ],
                "summary": "Create a quotation",
                "description": "Creates a quotation with its lines. No stock movement. Batch picks on lines are stored for later conversion. Note the order discount field is `Discount` (capital D) on create.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@store",
                "x-source": "app/Http/Controllers/QuotationsController.php#L187-L256",
                "x-route-name": "quotations.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Quotations_add",
                        "policy": "QuotationPolicy"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "Unit",
                    "QuotationDetail"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "Discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount amount."
                                    },
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Lines: `{product_id, product_variant_id, quantity, sale_unit_id, Unit_price, tax_percent, tax_method, discount, discount_Method, subtotal, imei_number, batches?}`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping cost.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`pending` or `sent`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    },
                                    "currency_id": {
                                        "type": "integer",
                                        "description": "Document currency id (multi-currency).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "exchange_rate": {
                                        "type": "number",
                                        "description": "Exchange rate snapshot.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "client_id": 3,
                                "warehouse_id": 1,
                                "date": "2026-09-06",
                                "statut": "pending",
                                "tax_rate": 0,
                                "TaxNet": 0,
                                "Discount": 0,
                                "shipping": 0,
                                "GrandTotal": 199,
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 10,
                                        "sale_unit_id": 1,
                                        "Unit_price": 19.9,
                                        "tax_percent": 0,
                                        "tax_method": "1",
                                        "discount": 0,
                                        "discount_Method": "2",
                                        "subtotal": 199,
                                        "imei_number": null
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotations/create": {
            "get": {
                "operationId": "get_api_quotations_create",
                "tags": [
                    "Quotations"
                ],
                "summary": "Get lookups for the quotation form",
                "description": "`clients`, the caller's `warehouses` and the `quotation_with_stock` setting (whether the form should enforce stock availability).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@create",
                "x-source": "app/Http/Controllers/QuotationsController.php#L952-L974",
                "x-route-name": "quotations.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Quotations_add",
                        "policy": "QuotationPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Client",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "quotation_with_stock": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotations/{quotation}": {
            "delete": {
                "operationId": "delete_api_quotations_quotation",
                "tags": [
                    "Quotations"
                ],
                "summary": "Delete a quotation",
                "description": "Soft-deletes the quotation and its lines (and clears batch picks).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@destroy",
                "x-source": "app/Http/Controllers/QuotationsController.php#L400-L460",
                "x-route-name": "quotations.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Quotations_delete",
                        "policy": "QuotationPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "UserWarehouse",
                    "QuotationDetail"
                ],
                "parameters": [
                    {
                        "name": "quotation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Quotation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_quotations_quotation",
                "tags": [
                    "Quotations"
                ],
                "summary": "Get a quotation",
                "description": "Detail view: `quote` header (`id, Ref, currency_*, date, note, statut, discount, shipping, tax_rate, TaxNet, client_* fields, warehouse, GrandTotal, converted_sale_id, converted_sale_ref`), `details[]` lines and `company`. Amounts in the document currency.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@show",
                "x-source": "app/Http/Controllers/QuotationsController.php#L530-L669",
                "x-route-name": "quotations.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Quotations_view",
                        "policy": "QuotationPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "Sale",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "quotation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Quotation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`quote`, `details[]`, `company`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "quote": {},
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "company": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_quotations_quotation",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Quotations"
                ],
                "summary": "Update a quotation",
                "description": "Replaces header and lines (matched by detail `id`). Here the discount field is lowercase `discount`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@update",
                "x-source": "app/Http/Controllers/QuotationsController.php#L260-L396",
                "x-route-name": "quotations.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Quotations_edit",
                        "policy": "QuotationPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "UserWarehouse",
                    "QuotationDetail"
                ],
                "parameters": [
                    {
                        "name": "quotation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Quotation id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`pending`/`sent`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_quotations_quotation",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Quotations"
                ],
                "summary": "Update a quotation",
                "description": "Replaces header and lines (matched by detail `id`). Here the discount field is lowercase `discount`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@update",
                "x-source": "app/Http/Controllers/QuotationsController.php#L260-L396",
                "x-route-name": "quotations.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Quotations_edit",
                        "policy": "QuotationPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "UserWarehouse",
                    "QuotationDetail"
                ],
                "parameters": [
                    {
                        "name": "quotation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Quotation id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`pending`/`sent`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/quotations/{quotation}/edit": {
            "get": {
                "operationId": "get_api_quotations_quotation_edit",
                "tags": [
                    "Quotations"
                ],
                "summary": "Get a quotation for editing",
                "description": "Form-shaped payload: `quote` (`client_id, warehouse_id, date, statut, tax_rate, TaxNet, discount, shipping, notes`), `details[]` (`id, detail_id, product_id, product_variant_id, code, name, quantity, sale_unit_id, Unit_price, Net_price, tax_percent, tax_method, discount, discount_Method, subtotal, stock, imei_number, batches`) plus `clients` and `warehouses`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@edit",
                "x-source": "app/Http/Controllers/QuotationsController.php#L978-L1184",
                "x-route-name": "quotations.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Quotations_edit",
                        "policy": "QuotationPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "UserWarehouse",
                    "Client",
                    "Warehouse",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "quotation",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Quotation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`quote`, `details[]`, `clients[]`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "quote": {},
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotations_client": {
            "get": {
                "operationId": "get_api_quotations_client",
                "tags": [
                    "Customers"
                ],
                "summary": "List a customer's quotations (ledger)",
                "description": "Paginated quotations for one customer, newest first. Rows: `id, date, Ref, statut, warehouse_name, client_name, GrandTotal`. `search` matches `Ref`, `statut`, warehouse and customer names.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@quotationsByClient",
                "x-source": "app/Http/Controllers/ClientController.php#L1299-L1357",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Quotation"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "x-exists": "clients,id",
                            "x-laravel-rules": [
                                "required",
                                "integer",
                                "exists:clients,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Customer id (query string, required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`quotations[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "quotations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotations_delete_by_selection": {
            "post": {
                "operationId": "post_api_quotations_delete_by_selection",
                "tags": [
                    "Quotations"
                ],
                "summary": "Delete several quotations",
                "description": "Soft-deletes each quotation in `selectedIds`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@delete_by_selection",
                "x-source": "app/Http/Controllers/QuotationsController.php#L464-L526",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Quotations_delete",
                        "policy": "QuotationPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "UserWarehouse",
                    "QuotationDetail"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of quotation ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotations_send_email": {
            "post": {
                "operationId": "post_api_quotations_send_email",
                "tags": [
                    "Quotations"
                ],
                "summary": "Email a quotation to the customer",
                "description": "Sends the *quotation* email template with `{contact_name}`, `{business_name}`, `{quotation_url}` (public PDF), `{quotation_number}`, `{total_amount}`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@SendEmail",
                "x-source": "app/Http/Controllers/QuotationsController.php#L1188-L1244",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Quotations_view",
                        "policy": "QuotationPolicy"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "Setting",
                    "EmailMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Quotation id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quotations_send_sms": {
            "post": {
                "operationId": "post_api_quotations_send_sms",
                "tags": [
                    "Quotations"
                ],
                "summary": "SMS a quotation to the customer",
                "description": "Sends the *quotation* SMS template through the default SMS gateway.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "QuotationsController@Send_SMS",
                "x-source": "app/Http/Controllers/QuotationsController.php#L1248-L1380",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Quotations_view",
                        "policy": "QuotationPolicy"
                    }
                ],
                "x-models": [
                    "Quotation",
                    "Setting",
                    "sms_gateway",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Quotation id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/quote_pdf/{id}": {
            "get": {
                "operationId": "get_api_quote_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Quotation PDF",
                "description": "A4 quotation following the `quotation` PDF template settings.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "QuotationsController@Quotation_pdf",
                "x-source": "app/Http/Controllers/QuotationsController.php#L706-L816",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Quotation",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Quotation ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file `Quotation_<Ref>.pdf`.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/quote_print_html/{id}": {
            "get": {
                "operationId": "get_api_quote_print_html_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Quotation HTML",
                "description": "Quotation template as HTML for the print popup.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "QuotationsController@Quotation_PDF_Inline",
                "x-source": "app/Http/Controllers/QuotationsController.php#L824-L948",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Quotation",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "html",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Quotation ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "HTML document (printable view)",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/qz/certificate": {
            "get": {
                "operationId": "get_api_qz_certificate",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get QZ Tray signing certificate",
                "description": "Public certificate used to sign QZ Tray requests. The qz-tray JS library fetches it on connect; the settings page also offers it for download so it can be installed as `override.crt` in QZ Tray for silent printing. Returns `certificate: null` with a message when the server cannot generate one, in which case QZ falls back to per-session Allow prompts.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@qzCertificate",
                "x-source": "app/Http/Controllers/SettingsController.php#L1535-L1544",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`{certificate: string|null, message?}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "certificate": {},
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/qz/sign": {
            "post": {
                "operationId": "post_api_qz_sign",
                "tags": [
                    "System Settings"
                ],
                "summary": "Sign a QZ Tray challenge",
                "description": "Signs the challenge string QZ Tray issues per print with the server's private key. Called automatically by the qz-tray JS library.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@qzSign",
                "x-source": "app/Http/Controllers/SettingsController.php#L1547-L1558",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "request": {
                                        "type": "string",
                                        "maxLength": 10000,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:10000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Challenge string from QZ Tray (max 10 000 chars)."
                                    }
                                },
                                "required": [
                                    "request"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{signature: string|null, message?}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "signature": {},
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/real_time_sales_counter_data": {
            "get": {
                "operationId": "get_api_real_time_sales_counter_data",
                "tags": [
                    "Dashboard"
                ],
                "summary": "Get real-time sales counter",
                "description": "Live figures for the sales-counter screen: today's sale count, total, paid and due; last sale timestamp; yesterday's total for trend; hourly breakdown; ten most recent sales; top products; payment-status split; sales by warehouse. Poll every few seconds. Requires the `real_time_sales_counter` permission.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "DashboardController@real_time_sales_counter_data",
                "x-source": "app/Http/Controllers/DashboardController.php#L1057-L1264",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Sale",
                    "SaleDetail"
                ],
                "parameters": [
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Restrict to one warehouse (`0` = all assigned; an unassigned ID is ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{today_count, today_total, today_paid, today_due, last_sale_at, yesterday_total, payment_status_counts, hourly: [{hour, total_invoice, amount}], recent_sales: [], top_products: [], sales_by_location, warehouses, selected_warehouse_id, server_time}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "ref": {},
                                        "date": {},
                                        "grand_total": {},
                                        "paid_amount": {
                                            "type": "integer"
                                        },
                                        "due_amount": {},
                                        "payment_status": {},
                                        "is_pos": {
                                            "type": "integer"
                                        },
                                        "client_name": {},
                                        "warehouse_name": {},
                                        "product_id": {},
                                        "product_name": {},
                                        "quantity": {
                                            "type": "number"
                                        },
                                        "total": {
                                            "type": "number"
                                        },
                                        "warehouse_id": {},
                                        "name": {},
                                        "total_invoice": {
                                            "type": "integer"
                                        },
                                        "amount": {
                                            "type": "number"
                                        },
                                        "last_sale": {
                                            "type": "string"
                                        },
                                        "today_count": {
                                            "type": "integer"
                                        },
                                        "today_total": {
                                            "type": "integer"
                                        },
                                        "today_paid": {
                                            "type": "integer"
                                        },
                                        "today_due": {
                                            "type": "integer"
                                        },
                                        "last_sale_at": {},
                                        "yesterday_total": {
                                            "type": "integer"
                                        },
                                        "payment_status_counts": {
                                            "type": "object",
                                            "properties": {
                                                "paid": {
                                                    "type": "integer"
                                                },
                                                "partial": {
                                                    "type": "integer"
                                                },
                                                "unpaid": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "hourly": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recent_sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "top_products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales_by_location": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "selected_warehouse_id": {
                                            "type": "integer"
                                        },
                                        "server_time": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "User lacks `real_time_sales_counter`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Unauthorized"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/categories": {
            "get": {
                "operationId": "get_api_realestate_categories",
                "tags": [
                    "Real Estate"
                ],
                "summary": "List property categories",
                "description": "Paginated property categories (e.g. Apartment, Villa, Office) with image and property count.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@categories_index",
                "x-source": "app/Http/Controllers/RealEstateController.php#L298-L323",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "realestate_categories",
                        "policy": "PropertyCategoryPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PropertyCategory"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`categories[]` (with `properties_count`) and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_realestate_categories",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Create a category",
                "description": "Creates a property category (name, description, optional image upload).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@categories_store",
                "x-source": "app/Http/Controllers/RealEstateController.php#L334-L354",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "realestate_categories",
                        "policy": "PropertyCategoryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyCategory"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "image_file": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp",
                                        "maxLength": 4096,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Image (max 4 MB)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/categories/{id}": {
            "delete": {
                "operationId": "delete_api_realestate_categories_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Delete a category",
                "description": "Properties are detached, not deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@categories_destroy",
                "x-source": "app/Http/Controllers/RealEstateController.php#L380-L390",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "realestate_categories",
                        "policy": "PropertyCategoryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyCategory",
                    "Property"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_realestate_categories_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Update a category (multipart)",
                "description": "Multipart variant of the category update, used when replacing the image (PHP cannot parse multipart `PUT`). Same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@categories_update",
                "x-source": "app/Http/Controllers/RealEstateController.php#L356-L378",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "realestate_categories",
                        "policy": "PropertyCategoryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyCategory"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "image_file": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp",
                                        "maxLength": 4096,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Image (max 4 MB)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_realestate_categories_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Update a category",
                "description": "Updates a category's name and description (JSON). Use the `POST …/{id}` variant to change the image.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@categories_update",
                "x-source": "app/Http/Controllers/RealEstateController.php#L356-L378",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "realestate_categories",
                        "policy": "PropertyCategoryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyCategory"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "image_file": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp",
                                        "maxLength": 4096,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Image (max 4 MB)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/categories_all": {
            "get": {
                "operationId": "get_api_realestate_categories_all",
                "tags": [
                    "Real Estate"
                ],
                "summary": "All categories (lookup)",
                "description": "All categories as `{id, name}` for select inputs.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@categories_all",
                "x-source": "app/Http/Controllers/RealEstateController.php#L325-L332",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "PropertyCategory"
                ],
                "responses": {
                    "200": {
                        "description": "`categories[] {id, name, slug}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/dashboard": {
            "get": {
                "operationId": "get_api_realestate_dashboard",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Real-estate dashboard",
                "description": "Real-estate KPIs: properties by status and purpose (sale/rent), featured count, new inquiries, inquiries by status and recent listings.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@dashboard",
                "x-source": "app/Http/Controllers/RealEstateController.php#L63-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "Property",
                    "PropertyCategory",
                    "PropertyInquiry"
                ],
                "responses": {
                    "200": {
                        "description": "`stats` (properties by status, featured, categories, inquiries), `latest_properties`, `latest_inquiries`, `by_purpose`, `by_status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "latest_properties": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "latest_inquiries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_purpose": {},
                                        "by_status": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/inquiries": {
            "get": {
                "operationId": "get_api_realestate_inquiries",
                "tags": [
                    "Real Estate"
                ],
                "summary": "List inquiries",
                "description": "Paginated inquiries submitted from the public listing pages: property, name, phone, email, message, status and date. Filter by `status` and `property_id`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@inquiries_index",
                "x-source": "app/Http/Controllers/RealEstateController.php#L408-L440",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "realestate_inquiries",
                        "policy": "PropertyInquiryPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PropertyInquiry"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`new`, `read`, `responded`, `closed`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`inquiries[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "inquiries": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/inquiries/delete/by_selection": {
            "post": {
                "operationId": "post_api_realestate_inquiries_delete_by_selection",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Delete selected inquiries",
                "description": "Bulk delete of inquiries by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@inquiries_delete_by_selection",
                "x-source": "app/Http/Controllers/RealEstateController.php#L481-L489",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "realestate_inquiries",
                        "policy": "PropertyInquiryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyInquiry"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Inquiry ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/inquiries/{id}": {
            "delete": {
                "operationId": "delete_api_realestate_inquiries_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Delete an inquiry",
                "description": "Deletes an inquiry.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@inquiries_destroy",
                "x-source": "app/Http/Controllers/RealEstateController.php#L472-L479",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "realestate_inquiries",
                        "policy": "PropertyInquiryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyInquiry"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Inquiry id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_realestate_inquiries_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Get an inquiry",
                "description": "Opening a `new` inquiry marks it `read`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@inquiries_show",
                "x-source": "app/Http/Controllers/RealEstateController.php#L442-L455",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "realestate_inquiries",
                        "policy": "PropertyInquiryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyInquiry"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Inquiry id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`inquiry`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "inquiry": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/inquiries/{id}/status": {
            "put": {
                "operationId": "put_api_realestate_inquiries_id_status",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Set inquiry status",
                "description": "Sets the inquiry status: `new`, `contacted`, `closed`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@inquiries_update_status",
                "x-source": "app/Http/Controllers/RealEstateController.php#L457-L470",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "realestate_inquiries",
                        "policy": "PropertyInquiryPolicy"
                    }
                ],
                "x-models": [
                    "PropertyInquiry"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Inquiry id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "new",
                                            "read",
                                            "responded",
                                            "closed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:new,read,responded,closed"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "New status."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/properties": {
            "get": {
                "operationId": "get_api_realestate_properties",
                "tags": [
                    "Real Estate"
                ],
                "summary": "List properties",
                "description": "Sortable `id, title, price, status, purpose, created_at`; `search` matches title, city or address.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@properties_index",
                "x-source": "app/Http/Controllers/RealEstateController.php#L105-L141",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Property"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category id or slug."
                    },
                    {
                        "name": "purpose",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`sale` / `rent`."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`available`, `sold`, `rented`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`properties[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "properties": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_realestate_properties",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Create a property",
                "description": "Multipart. `amenities` is a JSON array of strings; `gallery_files[]` uploads gallery images; `gallery_existing` (JSON array of paths) keeps previously uploaded ones on update.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@properties_store",
                "x-source": "app/Http/Controllers/RealEstateController.php#L152-L165",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "Property"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Address."
                                    },
                                    "agent_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent email."
                                    },
                                    "agent_name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent name."
                                    },
                                    "agent_phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent phone."
                                    },
                                    "agent_whatsapp": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent WhatsApp."
                                    },
                                    "amenities": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amenities JSON array.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "area": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Area."
                                    },
                                    "area_unit": {
                                        "type": "string",
                                        "maxLength": 12,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:12"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`m2`, `sqft`…"
                                    },
                                    "bathrooms": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bathrooms."
                                    },
                                    "bedrooms": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bedrooms."
                                    },
                                    "city": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "City."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description (HTML)."
                                    },
                                    "featured": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Featured on the home page.",
                                        "type": "boolean"
                                    },
                                    "featured_image_file": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp",
                                        "maxLength": 8192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:8192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Main image (max 8 MB)."
                                    },
                                    "gallery_existing": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "JSON array of kept gallery paths.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "gallery_files": {
                                        "type": "array",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Gallery images.",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "x-format": "mimes:jpg,jpeg,png,webp",
                                            "maxLength": 8192,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "file",
                                                "mimes:jpg,jpeg,png,webp",
                                                "max:8192"
                                            ]
                                        }
                                    },
                                    "garage": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Garage spaces."
                                    },
                                    "latitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Latitude."
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Longitude."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Price."
                                    },
                                    "property_category_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "property_categories,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:property_categories,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category."
                                    },
                                    "purpose": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sale",
                                            "rent"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:sale,rent"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`sale` or `rent`."
                                    },
                                    "region": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Region."
                                    },
                                    "seo_description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO description."
                                    },
                                    "seo_keywords": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO keywords."
                                    },
                                    "seo_title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO title."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "sold",
                                            "rented"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:available,sold,rented"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/properties/delete/by_selection": {
            "post": {
                "operationId": "post_api_realestate_properties_delete_by_selection",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Delete selected properties",
                "description": "Bulk soft-delete of properties by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@properties_delete_by_selection",
                "x-source": "app/Http/Controllers/RealEstateController.php#L192-L200",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "Property"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Property ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/realestate/properties/{id}": {
            "delete": {
                "operationId": "delete_api_realestate_properties_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Delete a property",
                "description": "Soft-deletes a property and removes it from the public listing.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@properties_destroy",
                "x-source": "app/Http/Controllers/RealEstateController.php#L183-L190",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "Property"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Property id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_realestate_properties_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Get a property",
                "description": "One property with category, gallery URLs, amenities, agent contact, SEO fields and inquiry count.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@properties_show",
                "x-source": "app/Http/Controllers/RealEstateController.php#L143-L150",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "Property"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Property id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`property`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "property": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_realestate_properties_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Update a property (multipart)",
                "description": "Multipart variant of the property update, used when uploading a new featured image or gallery files. Same fields as creation; `gallery_existing` lists the gallery file names to keep.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@properties_update",
                "x-source": "app/Http/Controllers/RealEstateController.php#L167-L181",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "Property"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Property id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Address."
                                    },
                                    "agent_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent email."
                                    },
                                    "agent_name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent name."
                                    },
                                    "agent_phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent phone."
                                    },
                                    "agent_whatsapp": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent WhatsApp."
                                    },
                                    "amenities": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amenities JSON array.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "area": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Area."
                                    },
                                    "area_unit": {
                                        "type": "string",
                                        "maxLength": 12,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:12"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`m2`, `sqft`…"
                                    },
                                    "bathrooms": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bathrooms."
                                    },
                                    "bedrooms": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bedrooms."
                                    },
                                    "city": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "City."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description (HTML)."
                                    },
                                    "featured": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Featured on the home page.",
                                        "type": "boolean"
                                    },
                                    "featured_image_file": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp",
                                        "maxLength": 8192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:8192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Main image (max 8 MB)."
                                    },
                                    "gallery_existing": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "File names of the gallery images to keep (array). Gallery files not listed are deleted; new uploads in `gallery_files` are appended.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "gallery_files": {
                                        "type": "array",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "New gallery images to add (multipart, multiple).",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "x-format": "mimes:jpg,jpeg,png,webp",
                                            "maxLength": 8192,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "file",
                                                "mimes:jpg,jpeg,png,webp",
                                                "max:8192"
                                            ]
                                        }
                                    },
                                    "garage": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Garage spaces."
                                    },
                                    "latitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Latitude."
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Longitude."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Price."
                                    },
                                    "property_category_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "property_categories,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:property_categories,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category."
                                    },
                                    "purpose": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sale",
                                            "rent"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:sale,rent"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`sale` or `rent`."
                                    },
                                    "region": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Region."
                                    },
                                    "seo_description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO description."
                                    },
                                    "seo_keywords": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO keywords."
                                    },
                                    "seo_title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO title."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "sold",
                                            "rented"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:available,sold,rented"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_realestate_properties_id",
                "tags": [
                    "Real Estate"
                ],
                "summary": "Update a property",
                "description": "Updates a property (JSON). Same fields as creation; use the `POST …/{id}` variant to upload images.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "RealEstateController@properties_update",
                "x-source": "app/Http/Controllers/RealEstateController.php#L167-L181",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "realestate_properties",
                        "policy": "PropertyPolicy"
                    }
                ],
                "x-models": [
                    "Property"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Property id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Address."
                                    },
                                    "agent_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent email."
                                    },
                                    "agent_name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent name."
                                    },
                                    "agent_phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent phone."
                                    },
                                    "agent_whatsapp": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Agent WhatsApp."
                                    },
                                    "amenities": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amenities JSON array.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "area": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Area."
                                    },
                                    "area_unit": {
                                        "type": "string",
                                        "maxLength": 12,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:12"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`m2`, `sqft`…"
                                    },
                                    "bathrooms": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bathrooms."
                                    },
                                    "bedrooms": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Bedrooms."
                                    },
                                    "city": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "City."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description (HTML)."
                                    },
                                    "featured": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Featured on the home page.",
                                        "type": "boolean"
                                    },
                                    "featured_image_file": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp",
                                        "maxLength": 8192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp",
                                            "max:8192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Main image (max 8 MB)."
                                    },
                                    "gallery_existing": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "File names of the gallery images to keep (array). Files not listed are deleted.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "gallery_files": {
                                        "type": "array",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Gallery images.",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "x-format": "mimes:jpg,jpeg,png,webp",
                                            "maxLength": 8192,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "file",
                                                "mimes:jpg,jpeg,png,webp",
                                                "max:8192"
                                            ]
                                        }
                                    },
                                    "garage": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Garage spaces."
                                    },
                                    "latitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Latitude."
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Longitude."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Price."
                                    },
                                    "property_category_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "property_categories,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:property_categories,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category."
                                    },
                                    "purpose": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sale",
                                            "rent"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:sale,rent"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`sale` or `rent`."
                                    },
                                    "region": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Region."
                                    },
                                    "seo_description": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO description."
                                    },
                                    "seo_keywords": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO keywords."
                                    },
                                    "seo_title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO title."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "available",
                                            "sold",
                                            "rented"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:available,sold,rented"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Status."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/applications": {
            "get": {
                "operationId": "get_api_recruit_applications",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List applications",
                "description": "Paginated applications with `job` and `candidate`. `search` matches the candidate's name or email.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@applications_index",
                "x-source": "app/Http/Controllers/RecruitController.php#L386-L425",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "recruit_application",
                        "policy": "RecruitApplicationPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "RecruitApplication"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "job_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on job."
                    },
                    {
                        "name": "stage",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "applied",
                                "screening",
                                "shortlisted",
                                "interview",
                                "offered",
                                "hired",
                                "rejected"
                            ]
                        },
                        "description": "Pipeline stage."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`applications[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "applications": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_recruit_applications",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Create an application",
                "description": "Links a candidate to a job. `applied_date` defaults to today; `stage` defaults to `applied`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@applications_store",
                "x-source": "app/Http/Controllers/RecruitController.php#L436-L451",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "recruit_application",
                        "policy": "RecruitApplicationPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "RecruitApplication"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "applied_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Application date (default today)."
                                    },
                                    "candidate_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "recruit_candidates,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:recruit_candidates,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Candidate id."
                                    },
                                    "job_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "recruit_jobs,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:recruit_jobs,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Job id."
                                    },
                                    "stage": {
                                        "type": "string",
                                        "enum": [
                                            "applied",
                                            "screening",
                                            "shortlisted",
                                            "interview",
                                            "offered",
                                            "hired",
                                            "rejected"
                                        ],
                                        "description": "Initial stage.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "cover_letter": {
                                        "type": "string",
                                        "description": "Cover letter text.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "rating": {
                                        "type": "integer",
                                        "description": "Reviewer rating.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "type": "string",
                                        "description": "Notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "candidate_id",
                                    "job_id"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/applications/delete/by_selection": {
            "post": {
                "operationId": "post_api_recruit_applications_delete_by_selection",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete selected applications",
                "description": "Bulk delete of applications by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@applications_delete_by_selection",
                "x-source": "app/Http/Controllers/RecruitController.php#L487-L496",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_application",
                        "policy": "RecruitApplicationPolicy"
                    }
                ],
                "x-models": [
                    "RecruitApplication"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Application ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/applications/{id}": {
            "delete": {
                "operationId": "delete_api_recruit_applications_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete an application",
                "description": "Deletes an application and its interviews.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@applications_destroy",
                "x-source": "app/Http/Controllers/RecruitController.php#L478-L485",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_application",
                        "policy": "RecruitApplicationPolicy"
                    }
                ],
                "x-models": [
                    "RecruitApplication"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Application id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_recruit_applications_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Update an application",
                "description": "Mass-updates any fillable field (`job_id, candidate_id, stage, applied_date, cover_letter, rating, notes`). No validation is applied.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@applications_update",
                "x-source": "app/Http/Controllers/RecruitController.php#L453-L461",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "recruit_application",
                        "policy": "RecruitApplicationPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "RecruitApplication"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Application id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": true,
                                "x-accepts-all-input": true,
                                "properties": {
                                    "job_id": {
                                        "type": "integer",
                                        "description": "Job.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "candidate_id": {
                                        "type": "integer",
                                        "description": "Candidate.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "stage": {
                                        "type": "string",
                                        "description": "Stage.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "applied_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Applied date.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "cover_letter": {
                                        "type": "string",
                                        "description": "Cover letter.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "rating": {
                                        "type": "integer",
                                        "description": "Rating.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "type": "string",
                                        "description": "Notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/applications/{id}/stage": {
            "put": {
                "operationId": "put_api_recruit_applications_id_stage",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Move an application to a stage",
                "description": "Sets `stage` and records `reviewed_by` / `reviewed_at` (used for time-to-hire).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@applications_update_stage",
                "x-source": "app/Http/Controllers/RecruitController.php#L463-L476",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "recruit_application",
                        "policy": "RecruitApplicationPolicy"
                    }
                ],
                "x-models": [
                    "RecruitApplication"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Application id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "stage": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "applied",
                                            "screening",
                                            "shortlisted",
                                            "interview",
                                            "offered",
                                            "hired",
                                            "rejected"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:applied,screening,shortlisted,interview,offered,hired,rejected"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target stage."
                                    }
                                },
                                "required": [
                                    "stage"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/applications_all": {
            "get": {
                "operationId": "get_api_recruit_applications_all",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List all applications (lookup)",
                "description": "All applications with `job:{id,title}` and `candidate:{id,first_name,last_name}`, newest first.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@applications_all",
                "x-source": "app/Http/Controllers/RecruitController.php#L427-L434",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "RecruitApplication"
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/candidates": {
            "get": {
                "operationId": "get_api_recruit_candidates",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List candidates",
                "description": "Paginated candidates with `applications_count`. `search` matches first name, last name or email.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@candidates_index",
                "x-source": "app/Http/Controllers/RecruitController.php#L270-L306",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "recruit_candidate",
                        "policy": "RecruitCandidatePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "RecruitCandidate"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "source",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on acquisition source (e.g. `website`, `linkedin`, `referral`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`candidates[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "candidates": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_recruit_candidates",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Create a candidate",
                "description": "Multipart. All other profile fields are stored as sent; `resume` and `photo` files are saved and their paths stored in `resume_path` / `photo`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@candidates_store",
                "x-source": "app/Http/Controllers/RecruitController.php#L315-L337",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "recruit_candidate",
                        "policy": "RecruitCandidatePolicy"
                    }
                ],
                "x-models": [
                    "RecruitCandidate"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "recruit_candidates,email",
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:recruit_candidates,email"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unique email."
                                    },
                                    "first_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "First name."
                                    },
                                    "last_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Last name."
                                    },
                                    "photo": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "except",
                                            "file"
                                        ],
                                        "description": "Photo image."
                                    },
                                    "resume": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "except",
                                            "file"
                                        ],
                                        "description": "Resume file (PDF/DOC)."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "Phone.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "date_of_birth": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Date of birth.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gender": {
                                        "type": "string",
                                        "description": "Gender.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "address": {
                                        "type": "string",
                                        "description": "Address.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "city": {
                                        "type": "string",
                                        "description": "City.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "state": {
                                        "type": "string",
                                        "description": "State / province.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "country": {
                                        "type": "string",
                                        "description": "Country.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "zip_code": {
                                        "type": "string",
                                        "description": "Postal code.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "current_company": {
                                        "type": "string",
                                        "description": "Current employer.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "current_position": {
                                        "type": "string",
                                        "description": "Current job title.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "current_salary": {
                                        "type": "number",
                                        "description": "Current salary.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "expected_salary": {
                                        "type": "number",
                                        "description": "Expected salary.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "experience_years": {
                                        "type": "integer",
                                        "description": "Years of experience.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "skills": {
                                        "type": "string",
                                        "description": "Skills (free text).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "education": {
                                        "type": "string",
                                        "description": "Education summary.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "linkedin_url": {
                                        "type": "string",
                                        "description": "LinkedIn URL.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "portfolio_url": {
                                        "type": "string",
                                        "description": "Portfolio URL.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "type": "string",
                                        "description": "Internal notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "source": {
                                        "type": "string",
                                        "description": "Acquisition source.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "email",
                                    "first_name",
                                    "last_name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/candidates/delete/by_selection": {
            "post": {
                "operationId": "post_api_recruit_candidates_delete_by_selection",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete selected candidates",
                "description": "Bulk delete of candidates by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@candidates_delete_by_selection",
                "x-source": "app/Http/Controllers/RecruitController.php#L373-L382",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_candidate",
                        "policy": "RecruitCandidatePolicy"
                    }
                ],
                "x-models": [
                    "RecruitCandidate"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Candidate ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/candidates/{id}": {
            "delete": {
                "operationId": "delete_api_recruit_candidates_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete a candidate",
                "description": "Deletes a candidate with their applications and CV file.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@candidates_destroy",
                "x-source": "app/Http/Controllers/RecruitController.php#L364-L371",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_candidate",
                        "policy": "RecruitCandidatePolicy"
                    }
                ],
                "x-models": [
                    "RecruitCandidate"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Candidate id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_recruit_candidates_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Update a candidate",
                "description": "Same fields as create; `email` must stay unique (excluding this candidate).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@candidates_update",
                "x-source": "app/Http/Controllers/RecruitController.php#L339-L362",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "recruit_candidate",
                        "policy": "RecruitCandidatePolicy"
                    }
                ],
                "x-models": [
                    "RecruitCandidate"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Candidate id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "x-rules": [
                                            "dynamic:'required|email|unique:recruit_candidates,email,' . $id"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'required|email|unique:recruit_candidates,email,' . $id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email.",
                                        "type": "string"
                                    },
                                    "first_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "First name."
                                    },
                                    "last_name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Last name."
                                    },
                                    "photo": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "except",
                                            "file"
                                        ],
                                        "description": "New photo."
                                    },
                                    "resume": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "except",
                                            "file"
                                        ],
                                        "description": "New resume file."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "description": "Phone.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "gender": {
                                        "type": "string",
                                        "description": "Gender.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "city": {
                                        "type": "string",
                                        "description": "City.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "country": {
                                        "type": "string",
                                        "description": "Country.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "current_company": {
                                        "type": "string",
                                        "description": "Current employer.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "current_position": {
                                        "type": "string",
                                        "description": "Current title.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "expected_salary": {
                                        "type": "number",
                                        "description": "Expected salary.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "experience_years": {
                                        "type": "integer",
                                        "description": "Years of experience.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "skills": {
                                        "type": "string",
                                        "description": "Skills.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "source": {
                                        "type": "string",
                                        "description": "Source.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "type": "string",
                                        "description": "Notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "first_name",
                                    "last_name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/candidates_all": {
            "get": {
                "operationId": "get_api_recruit_candidates_all",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List all candidates (lookup)",
                "description": "`{id, first_name, last_name, email}` ordered by first name.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@candidates_all",
                "x-source": "app/Http/Controllers/RecruitController.php#L308-L313",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "RecruitCandidate"
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/categories": {
            "get": {
                "operationId": "get_api_recruit_categories",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List job categories",
                "description": "Paginated with `jobs_count`. `search` matches the name.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@categories_index",
                "x-source": "app/Http/Controllers/RecruitController.php#L76-L104",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "recruit_category",
                        "policy": "RecruitJobCategoryPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "RecruitJobCategory"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`categories[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_recruit_categories",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Create a job category",
                "description": "Creates a job category used to group job postings.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@categories_store",
                "x-source": "app/Http/Controllers/RecruitController.php#L113-L126",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "recruit_category",
                        "policy": "RecruitJobCategoryPolicy"
                    }
                ],
                "x-models": [
                    "RecruitJobCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag (default true)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (max 255)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/categories/delete/by_selection": {
            "post": {
                "operationId": "post_api_recruit_categories_delete_by_selection",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete selected job categories",
                "description": "Bulk delete of job categories by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@categories_delete_by_selection",
                "x-source": "app/Http/Controllers/RecruitController.php#L152-L161",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_category",
                        "policy": "RecruitJobCategoryPolicy"
                    }
                ],
                "x-models": [
                    "RecruitJobCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Category ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/categories/{id}": {
            "delete": {
                "operationId": "delete_api_recruit_categories_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete a job category",
                "description": "Deletes a job category; jobs keep their `category_id`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@categories_destroy",
                "x-source": "app/Http/Controllers/RecruitController.php#L143-L150",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_category",
                        "policy": "RecruitJobCategoryPolicy"
                    }
                ],
                "x-models": [
                    "RecruitJobCategory"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_recruit_categories_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Update a job category",
                "description": "Renames a job category.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@categories_update",
                "x-source": "app/Http/Controllers/RecruitController.php#L128-L141",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "recruit_category",
                        "policy": "RecruitJobCategoryPolicy"
                    }
                ],
                "x-models": [
                    "RecruitJobCategory"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/categories_all": {
            "get": {
                "operationId": "get_api_recruit_categories_all",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List active job categories (lookup)",
                "description": "`{id, name}` of active categories ordered by name.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@categories_all",
                "x-source": "app/Http/Controllers/RecruitController.php#L106-L111",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "RecruitJobCategory"
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/dashboard": {
            "get": {
                "operationId": "get_api_recruit_dashboard",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Recruitment dashboard",
                "description": "`stats` (`total_jobs, open_jobs, total_candidates, total_applications, pending_interviews, hired_count`), the 10 most recent `recent_applications`, the next 10 `upcoming_interviews` and the `pipeline` (count per stage).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@dashboard",
                "x-source": "app/Http/Controllers/RecruitController.php#L36-L72",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "recruit_job",
                        "policy": "RecruitJobPolicy"
                    }
                ],
                "x-models": [
                    "RecruitJob",
                    "RecruitCandidate",
                    "RecruitApplication",
                    "RecruitInterview"
                ],
                "responses": {
                    "200": {
                        "description": "`stats`, `recent_applications[]`, `upcoming_interviews[]`, `pipeline`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recent_applications": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "upcoming_interviews": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "pipeline": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/interviews": {
            "get": {
                "operationId": "get_api_recruit_interviews",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List interviews",
                "description": "Paginated interviews with `application.candidate` and `application.job`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@interviews_index",
                "x-source": "app/Http/Controllers/RecruitController.php#L500-L531",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "recruit_interview",
                        "policy": "RecruitInterviewPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "RecruitInterview"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "application_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on application."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`scheduled`, `completed`, `cancelled`, `no_show`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`interviews[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "interviews": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_recruit_interviews",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Schedule an interview",
                "description": "Creates the interview and auto-advances the application to `interview` if it is still in `applied`, `screening` or `shortlisted`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@interviews_store",
                "x-source": "app/Http/Controllers/RecruitController.php#L533-L552",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "recruit_interview",
                        "policy": "RecruitInterviewPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "RecruitInterview",
                    "RecruitApplication"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "application_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "recruit_applications,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:recruit_applications,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Application id."
                                    },
                                    "scheduled_at": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Date-time of the interview.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "phone",
                                            "video",
                                            "in_person",
                                            "technical",
                                            "panel",
                                            "group"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:phone,video,in_person,technical,panel,group"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`phone`, `video`, `in_person`, `technical`, `panel` or `group`."
                                    },
                                    "duration_minutes": {
                                        "type": "integer",
                                        "description": "Planned duration.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "location": {
                                        "type": "string",
                                        "description": "Location (in person).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "meeting_link": {
                                        "type": "string",
                                        "description": "Video link.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "interviewer_id": {
                                        "type": "integer",
                                        "description": "Interviewer user id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "status": {
                                        "type": "string",
                                        "description": "`scheduled` (default), `completed`, `cancelled`, `no_show`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "type": "string",
                                        "description": "Notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "application_id",
                                    "scheduled_at",
                                    "type"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            },
                            "example": {
                                "application_id": 12,
                                "scheduled_at": "2026-09-10 10:30:00",
                                "type": "video",
                                "duration_minutes": 45,
                                "meeting_link": "https://meet.example.com/abc",
                                "interviewer_id": 3
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/interviews/delete/by_selection": {
            "post": {
                "operationId": "post_api_recruit_interviews_delete_by_selection",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete selected interviews",
                "description": "Bulk delete of interviews by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@interviews_delete_by_selection",
                "x-source": "app/Http/Controllers/RecruitController.php#L580-L589",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_interview",
                        "policy": "RecruitInterviewPolicy"
                    }
                ],
                "x-models": [
                    "RecruitInterview"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Interview ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/interviews/{id}": {
            "delete": {
                "operationId": "delete_api_recruit_interviews_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete an interview",
                "description": "Deletes an interview.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@interviews_destroy",
                "x-source": "app/Http/Controllers/RecruitController.php#L571-L578",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_interview",
                        "policy": "RecruitInterviewPolicy"
                    }
                ],
                "x-models": [
                    "RecruitInterview"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Interview id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_recruit_interviews_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Update an interview",
                "description": "Updates scheduling details and, after the interview, `status`, `rating` and `feedback`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@interviews_update",
                "x-source": "app/Http/Controllers/RecruitController.php#L554-L569",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "recruit_interview",
                        "policy": "RecruitInterviewPolicy"
                    }
                ],
                "x-models": [
                    "RecruitInterview"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Interview id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "application_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Application."
                                    },
                                    "duration_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Duration in minutes.",
                                        "type": "integer"
                                    },
                                    "feedback": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Feedback text."
                                    },
                                    "interviewer_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Interviewer user id."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location."
                                    },
                                    "meeting_link": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Video link."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "rating": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Score given by the interviewer.",
                                        "type": "integer"
                                    },
                                    "scheduled_at": {
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`scheduled`, `completed`, `cancelled`, `no_show`."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "phone",
                                            "video",
                                            "in_person",
                                            "technical",
                                            "panel",
                                            "group"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:phone,video,in_person,technical,panel,group"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Interview type."
                                    }
                                },
                                "required": [
                                    "scheduled_at",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/jobs": {
            "get": {
                "operationId": "get_api_recruit_jobs",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List jobs",
                "description": "Paginated jobs with their `category` and `applications_count`. `search` matches the title.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@jobs_index",
                "x-source": "app/Http/Controllers/RecruitController.php#L165-L200",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "recruit_job",
                        "policy": "RecruitJobPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "RecruitJob"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category filter."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Job status (e.g. `open`, `closed`, `draft`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`jobs[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "jobs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_recruit_jobs",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Create a job",
                "description": "Stores every fillable field sent; a unique `slug` is generated from the title and `created_by` is set to the caller.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@jobs_store",
                "x-source": "app/Http/Controllers/RecruitController.php#L209-L226",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "recruit_job",
                        "policy": "RecruitJobPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "RecruitJob"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Job description."
                                    },
                                    "job_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "full_time",
                                            "part_time",
                                            "contract",
                                            "internship",
                                            "remote"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:full_time,part_time,contract,internship,remote"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`full_time`, `part_time`, `contract`, `internship` or `remote`."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Job title."
                                    },
                                    "category_id": {
                                        "type": "integer",
                                        "description": "Job category.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "department_id": {
                                        "type": "integer",
                                        "description": "HR department.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "location": {
                                        "type": "string",
                                        "description": "Location.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "requirements": {
                                        "type": "string",
                                        "description": "Requirements text.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "benefits": {
                                        "type": "string",
                                        "description": "Benefits text.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "salary_min": {
                                        "type": "number",
                                        "description": "Salary range minimum.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "salary_max": {
                                        "type": "number",
                                        "description": "Salary range maximum.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "currency": {
                                        "type": "string",
                                        "description": "Salary currency code.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "vacancies": {
                                        "type": "integer",
                                        "description": "Number of openings.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "status": {
                                        "type": "string",
                                        "description": "`open`, `closed`, `draft`, `on_hold` (free text; dashboard counts `open`).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "experience_level": {
                                        "type": "string",
                                        "description": "e.g. `junior`, `mid`, `senior`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "deadline": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Application deadline.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "description",
                                    "job_type",
                                    "title"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            },
                            "example": {
                                "title": "Warehouse Supervisor",
                                "description": "Runs the night shift…",
                                "job_type": "full_time",
                                "category_id": 2,
                                "department_id": 3,
                                "location": "Casablanca",
                                "salary_min": 6000,
                                "salary_max": 8000,
                                "currency": "MAD",
                                "vacancies": 1,
                                "status": "open",
                                "experience_level": "mid",
                                "deadline": "2026-10-31"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/jobs/delete/by_selection": {
            "post": {
                "operationId": "post_api_recruit_jobs_delete_by_selection",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete selected jobs",
                "description": "Bulk delete of job postings by `selectedIds`.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@jobs_delete_by_selection",
                "x-source": "app/Http/Controllers/RecruitController.php#L257-L266",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_job",
                        "policy": "RecruitJobPolicy"
                    }
                ],
                "x-models": [
                    "RecruitJob"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Job ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/jobs/{id}": {
            "delete": {
                "operationId": "delete_api_recruit_jobs_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Delete a job",
                "description": "Deletes a job posting with its applications.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@jobs_destroy",
                "x-source": "app/Http/Controllers/RecruitController.php#L248-L255",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "recruit_job",
                        "policy": "RecruitJobPolicy"
                    }
                ],
                "x-models": [
                    "RecruitJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_recruit_jobs_id",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Update a job",
                "description": "Same fields as create; the slug is regenerated when the title changes.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@jobs_update",
                "x-source": "app/Http/Controllers/RecruitController.php#L228-L246",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "recruit_job",
                        "policy": "RecruitJobPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "RecruitJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "job_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "full_time",
                                            "part_time",
                                            "contract",
                                            "internship",
                                            "remote"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:full_time,part_time,contract,internship,remote"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Job type."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    },
                                    "category_id": {
                                        "type": "integer",
                                        "description": "Category.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "department_id": {
                                        "type": "integer",
                                        "description": "Department.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "location": {
                                        "type": "string",
                                        "description": "Location.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "requirements": {
                                        "type": "string",
                                        "description": "Requirements.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "benefits": {
                                        "type": "string",
                                        "description": "Benefits.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "salary_min": {
                                        "type": "number",
                                        "description": "Min salary.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "salary_max": {
                                        "type": "number",
                                        "description": "Max salary.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "currency": {
                                        "type": "string",
                                        "description": "Currency.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "vacancies": {
                                        "type": "integer",
                                        "description": "Openings.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "status": {
                                        "type": "string",
                                        "description": "Status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "experience_level": {
                                        "type": "string",
                                        "description": "Experience level.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "deadline": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "Deadline.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "description",
                                    "job_type",
                                    "title"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/jobs_all": {
            "get": {
                "operationId": "get_api_recruit_jobs_all",
                "tags": [
                    "Recruitment"
                ],
                "summary": "List all jobs (lookup)",
                "description": "`{id, title, status}` ordered by title.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@jobs_all",
                "x-source": "app/Http/Controllers/RecruitController.php#L202-L207",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-models": [
                    "RecruitJob"
                ],
                "responses": {
                    "200": {
                        "description": "Array.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/recruit/reports": {
            "get": {
                "operationId": "get_api_recruit_reports",
                "tags": [
                    "Recruitment"
                ],
                "summary": "Recruitment reports",
                "description": "Aggregates for the period: `funnel` (applications per stage), `by_job` (top 10), `by_source` (candidates per source), `monthly_trend` (`month, total, hired, rejected`), `avg_time_to_hire` (days between applied and reviewed for hired applications) and `by_category` (jobs per category).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "RecruitController@reports",
                "x-source": "app/Http/Controllers/RecruitController.php#L593-L656",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "recruit_job",
                        "policy": "RecruitJobPolicy"
                    }
                ],
                "x-models": [
                    "RecruitApplication",
                    "RecruitCandidate",
                    "RecruitJob"
                ],
                "parameters": [
                    {
                        "name": "period",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "1month",
                                "3months",
                                "6months",
                                "1year"
                            ]
                        },
                        "description": "Reporting window."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Report object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "funnel": {},
                                        "by_job": {},
                                        "by_source": {},
                                        "monthly_trend": {},
                                        "avg_time_to_hire": {
                                            "type": "number"
                                        },
                                        "by_category": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/remove_draft_sale/{id}": {
            "delete": {
                "operationId": "delete_api_remove_draft_sale_id",
                "tags": [
                    "POS"
                ],
                "summary": "Delete a draft sale",
                "description": "Soft-deletes the draft and its lines.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "PosController@remove_draft_sale",
                "x-source": "app/Http/Controllers/PosController.php#L1144-L1163",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Sales_pos",
                        "slug": "Pos_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "DraftSale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Draft sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report-questions": {
            "get": {
                "operationId": "get_api_report_questions",
                "tags": [
                    "Report Questions"
                ],
                "summary": "List report questions",
                "description": "Active questions ordered for display, plus the caller's warehouses for the selector.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportQuestionController@index",
                "x-source": "app/Http/Controllers/ReportQuestionController.php#L29-L52",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "AI_Reports",
                        "slug": "AI_Reports",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "ReportQuestion",
                    "Warehouse",
                    "UserWarehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`{questions: [{id, title, report_key, needs_insights}], warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "questions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report-questions/run": {
            "post": {
                "operationId": "post_api_report_questions_run",
                "tags": [
                    "Report Questions"
                ],
                "summary": "Run a report question",
                "description": "Executes the query behind a question for the given filters and returns the rows, an optional comparison against the previous period and generated insight sentences.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportQuestionController@run",
                "x-source": "app/Http/Controllers/ReportQuestionController.php#L60-L158",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "AI_Reports",
                        "slug": "AI_Reports",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "ReportQuestion"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date_from": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start date."
                                    },
                                    "date_to": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:date_from"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:date_from"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End date (must be ≥ `date_from`)."
                                    },
                                    "question_id": {
                                        "type": "integer",
                                        "x-exists": "report_questions,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:report_questions,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Question ID from the list."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse filter."
                                    }
                                },
                                "required": [
                                    "question_id"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            },
                            "example": {
                                "question_id": 3,
                                "warehouse_id": 1,
                                "date_from": "2026-08-01",
                                "date_to": "2026-08-31"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{question, filters, data: [], compare, insights: []}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "question": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "title": {},
                                                "report_key": {}
                                            }
                                        },
                                        "filters": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "compare": {},
                                        "insights": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation error envelope.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "errors": {}
                                    },
                                    "x-envelope": "sendError"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/analytics_summary": {
            "get": {
                "operationId": "get_api_report_analytics_summary",
                "tags": [
                    "Reports"
                ],
                "summary": "Analytics summary",
                "description": "Opening/closing stock values (at purchase and sale price), purchases, sales, returns, discounts, shipping, expenses, adjustments and customer rewards for the range. The building blocks of the P&L overview page.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@analyticsSummary",
                "x-source": "app/Http/Controllers/ReportController.php#L2791-L3236",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_profit",
                        "slug": "Reports_profit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Purchase",
                    "Sale",
                    "SaleReturn",
                    "PurchaseReturn",
                    "Expense",
                    "Transfer"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Flat object of totals (`opening_stock_purchase_price`, `closing_stock_sale_price`, `total_sales_excl_tax`, `total_purchase_excl_tax`, `total_expense`, ...) plus `warehouses`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "cost": {},
                                        "price": {},
                                        "adjustment_abs_cost": {},
                                        "opening_stock_purchase_price": {
                                            "type": "number"
                                        },
                                        "opening_stock_sale_price": {
                                            "type": "number"
                                        },
                                        "total_purchase_excl_tax": {},
                                        "total_stock_adjustment": {},
                                        "total_expense": {},
                                        "total_purchase_shipping_charge": {},
                                        "total_transfer_shipping_charge": {},
                                        "total_sell_discount": {
                                            "type": "integer"
                                        },
                                        "total_customer_reward": {},
                                        "total_sell_return": {},
                                        "closing_stock_purchase_price": {
                                            "type": "number"
                                        },
                                        "closing_stock_sale_price": {
                                            "type": "number"
                                        },
                                        "total_sales_excl_tax": {},
                                        "total_sell_shipping_charge": {},
                                        "total_purchase_return": {},
                                        "total_purchase_discount": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/attendance_summary": {
            "get": {
                "operationId": "get_api_report_attendance_summary",
                "tags": [
                    "Reports"
                ],
                "summary": "Attendance summary",
                "description": "Per-employee attendance for a day (`scope=daily`) or a month (`scope=monthly`): present/absent/late counts and worked hours.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@attendance_summary",
                "x-source": "app/Http/Controllers/ReportController.php#L9070-L9180",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report_attendance_summary",
                        "slug": "report_attendance_summary",
                        "policy": "AttendancePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Company",
                    "Employee"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "company_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Company filter."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Day for the daily scope (default today)."
                    },
                    {
                        "name": "employee_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Employee filter."
                    },
                    {
                        "name": "month",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`YYYY-MM` or `MM` for the monthly scope."
                    },
                    {
                        "name": "scope",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "daily",
                                "monthly"
                            ]
                        },
                        "description": "Reporting scope (default `daily`)."
                    },
                    {
                        "name": "year",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year when `month` is only `MM`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [], totalRows, companies, employees, from, to, scope}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "from": {},
                                        "to": {},
                                        "scope": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/batches/register": {
            "get": {
                "operationId": "get_api_report_batches_register",
                "tags": [
                    "Batch Reports"
                ],
                "summary": "Batch register",
                "description": "Every batch with product, warehouse, expiry, quantity, cost, value, expiry bucket and the originating purchase/supplier. Filter by expiry window, status, supplier, warehouse and purchase date.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "BatchReportController@register",
                "x-source": "app/Http/Controllers/BatchReportController.php#L32-L252",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "Setting",
                    "UserWarehouse",
                    "PurchaseDetailBatch",
                    "ProductBatch",
                    "Warehouse",
                    "Provider"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "expiry_window",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "expired",
                                "near",
                                "valid",
                                "expired_or_near",
                                "all"
                            ]
                        },
                        "description": "Expiry bucket (default `all`)."
                    },
                    {
                        "name": "purchase_date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Originating purchase date from."
                    },
                    {
                        "name": "purchase_date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Originating purchase date to."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Batch status (`active`, `depleted`, `expired`, `quarantined`)."
                    },
                    {
                        "name": "supplier_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Originating supplier filter."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{batches: [{id, batch_no, product_name, warehouse_name, expiry_date, mfg_date, qty, unit_cost, value, status, days_to_expiry, expiry_bucket, origin_purchase_ref, origin_supplier_name}], totalRows, warehouses, suppliers, expiry_warning_days, supported}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "batches": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "expiry_warning_days": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "supported": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {
                                            "type": "integer"
                                        },
                                        "batch_no": {
                                            "type": "string"
                                        },
                                        "product_id": {
                                            "type": "integer"
                                        },
                                        "product_name": {},
                                        "product_code": {},
                                        "generic_name": {},
                                        "strength": {},
                                        "dosage_form": {},
                                        "variant_name": {},
                                        "warehouse_id": {
                                            "type": "integer"
                                        },
                                        "warehouse_name": {},
                                        "expiry_date": {},
                                        "mfg_date": {
                                            "type": "string"
                                        },
                                        "qty": {
                                            "type": "number"
                                        },
                                        "unit_cost": {},
                                        "value": {},
                                        "status": {
                                            "type": "string"
                                        },
                                        "days_to_expiry": {},
                                        "expiry_bucket": {},
                                        "origin_purchase_id": {
                                            "type": "integer"
                                        },
                                        "origin_purchase_ref": {},
                                        "origin_purchase_date": {
                                            "type": "string"
                                        },
                                        "origin_supplier_id": {
                                            "type": "integer"
                                        },
                                        "origin_supplier_name": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/batches/{id}/history": {
            "get": {
                "operationId": "get_api_report_batches_id_history",
                "tags": [
                    "Batch Reports"
                ],
                "summary": "Batch movement history",
                "description": "Unified movement log for one batch (purchase, sale, return, transfer, adjustment lines) with reconciliation totals and the batch header.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "BatchReportController@history",
                "x-source": "app/Http/Controllers/BatchReportController.php#L260-L326",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "ProductBatch",
                    "UserWarehouse",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Batch ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{supported, batch: {...}, movements: [{date, type, ref, qty_in, qty_out, balance}], totals}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supported": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Error"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/cash_flow_report": {
            "get": {
                "operationId": "get_api_report_cash_flow_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Cash flow report",
                "description": "Cash inflows (sale payments, deposits, opening balances) and outflows (purchase payments, expenses) grouped by account or by payment method, with a daily series.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@cash_flow_report",
                "x-source": "app/Http/Controllers/ReportController.php#L8074-L8558",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "cash_flow_report",
                        "slug": "cash_flow_report",
                        "policy": "PaymentSalePolicy"
                    }
                ],
                "x-models": [
                    "UserWarehouse",
                    "PaymentSale",
                    "PaymentOpeningBalance",
                    "Deposit",
                    "PaymentPurchase",
                    "ProviderPaymentOpeningBalance",
                    "Expense",
                    "Warehouse",
                    "PaymentMethod",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "account_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Account filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "group_by",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "account",
                                "method"
                            ]
                        },
                        "description": "Group by finance account (default) or payment method."
                    },
                    {
                        "name": "payment_method_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Payment method filter."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{rows: [{name, inflow, outflow, net}], total_inflow, total_outflow, net_cash_flow, group_by, timeseries, warehouses, payment_methods, accounts}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "d": {},
                                        "inflow": {
                                            "type": "number"
                                        },
                                        "outflow": {
                                            "type": "number"
                                        },
                                        "net": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "total_inflow": {
                                            "type": "number"
                                        },
                                        "total_outflow": {
                                            "type": "number"
                                        },
                                        "net_cash_flow": {
                                            "type": "number"
                                        },
                                        "group_by": {},
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/cash_registers": {
            "get": {
                "operationId": "get_api_report_cash_registers",
                "tags": [
                    "Cash Registers"
                ],
                "summary": "Cash register report",
                "description": "Paginated register sessions with user and warehouse, defaulting to the last 7 days. Rows: `id, user, warehouse, opened_at, closed_at, opening_balance, cash_in, cash_out, total_sales, closing_balance, difference, status, notes`. Sortable by `opened_at, closed_at, opening_balance, closing_balance, cash_in, cash_out, total_sales, difference, status, warehouse_id, user_id`. Also returns `users` and `warehouses` lookups.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "CashRegisterController@report",
                "x-source": "app/Http/Controllers/CashRegisterController.php#L149-L281",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "cash_register_report",
                        "slug": "cash_register_report",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "CashRegister",
                    "User",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (default: 6 days ago)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`open` or `closed`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (default: today)."
                    },
                    {
                        "name": "user_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this cashier."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`registers[]`, `totalRows`, `users[]`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "registers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "users": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/client": {
            "get": {
                "operationId": "get_api_report_client",
                "tags": [
                    "Reports"
                ],
                "summary": "Customers report",
                "description": "Per-customer totals: number of sales, total amount, paid and due, with a summary, top customers and top debtors. Sortable and searchable by name/phone/email.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Client_Report",
                "x-source": "app/Http/Controllers/ReportController.php#L106-L262",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_customers",
                        "slug": "Reports_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{id, name, phone, total_sales, total_amount, total_paid, due}], totalRows, summary, top_customers, top_debtors}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "value": {
                                            "type": "number"
                                        },
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "top_customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "top_debtors": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/client/{id}": {
            "get": {
                "operationId": "get_api_report_client_id",
                "tags": [
                    "Reports"
                ],
                "summary": "Customer report header",
                "description": "Totals for one customer: sales count, total amount, paid, due, returns.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Client_Report_detail",
                "x-source": "app/Http/Controllers/ReportController.php#L266-L293",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_customers",
                        "slug": "Reports_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: {total_sales, total_amount, total_paid, due, total_returns...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/client_payments": {
            "get": {
                "operationId": "get_api_report_client_payments",
                "tags": [
                    "Reports"
                ],
                "summary": "Customer payments list",
                "description": "Paginated payments received from one customer.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Payments_Client",
                "x-source": "app/Http/Controllers/ReportController.php#L412-L494",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_customers",
                        "slug": "Reports_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{payments: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/client_pdf/{id}": {
            "get": {
                "operationId": "get_api_report_client_pdf_id",
                "tags": [
                    "Reports"
                ],
                "summary": "Customer statement PDF",
                "description": "PDF listing the customer's unpaid/partially paid sales with the outstanding balance.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@download_report_client_pdf",
                "x-source": "app/Http/Controllers/ReportController.php#L5463-L5543",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_customers",
                        "slug": "Reports_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Sale",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/client_quotations": {
            "get": {
                "operationId": "get_api_report_client_quotations",
                "tags": [
                    "Reports"
                ],
                "summary": "Customer quotations list",
                "description": "Paginated quotations of one customer (`id`), scoped to the caller's warehouses and record view. `search` matches the reference.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Quotations_Client",
                "x-source": "app/Http/Controllers/ReportController.php#L498-L571",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_customers",
                        "slug": "Reports_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Quotation"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{quotations: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "quotations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/client_returns": {
            "get": {
                "operationId": "get_api_report_client_returns",
                "tags": [
                    "Reports"
                ],
                "summary": "Customer returns list",
                "description": "Paginated sale returns of one customer (`id`) with reference, date, total, paid and status.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Returns_Client",
                "x-source": "app/Http/Controllers/ReportController.php#L575-L657",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_customers",
                        "slug": "Reports_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SaleReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{returns_customer: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "returns_customer": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/client_sales": {
            "get": {
                "operationId": "get_api_report_client_sales",
                "tags": [
                    "Reports"
                ],
                "summary": "Customer sales list",
                "description": "Paginated sales of one customer.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Sales_Client",
                "x-source": "app/Http/Controllers/ReportController.php#L331-L408",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_customers",
                        "slug": "Reports_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/count_quantity_alert": {
            "get": {
                "operationId": "get_api_report_count_quantity_alert",
                "tags": [
                    "Reports"
                ],
                "summary": "Count stock alerts",
                "description": "Number of product/warehouse rows whose quantity is at or below the product's `stock_alert`, within the caller's warehouses. Used for the sidebar badge.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@count_quantity_alert",
                "x-source": "app/Http/Controllers/ReportController.php#L2539-L2548",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "product_warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "Integer count.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/customer_loyalty_points": {
            "get": {
                "operationId": "get_api_report_customer_loyalty_points",
                "tags": [
                    "Reports"
                ],
                "summary": "Customer loyalty points",
                "description": "Points earned, redeemed and current balance per customer for the range, with totals, a time series and top members.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@customerLoyaltyPoints",
                "x-source": "app/Http/Controllers/ReportController.php#L10291-L10396",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "customer_loyalty_points_report",
                        "slug": "customer_loyalty_points_report",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{rows: [{client_id, client_name, earned_points, redeemed_points, current_points}], totalRows, totals, timeseries, top_members}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "client_id": {
                                            "type": "integer"
                                        },
                                        "client_name": {},
                                        "earned_points": {
                                            "type": "number"
                                        },
                                        "redeemed_points": {
                                            "type": "number"
                                        },
                                        "current_points": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "earned_total": {
                                                    "type": "number"
                                                },
                                                "redeemed_total": {
                                                    "type": "number"
                                                },
                                                "balance_total": {
                                                    "type": "number"
                                                }
                                            }
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "top_members": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/customer_maintenance_history": {
            "get": {
                "operationId": "get_api_report_customer_maintenance_history",
                "tags": [
                    "Service Reports"
                ],
                "summary": "Customer maintenance history",
                "description": "Paginated jobs for a customer (or all), newest first, with client and technician names.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceReportController@customerMaintenanceHistory",
                "x-source": "app/Http/Controllers/ServiceReportController.php#L189-L258",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "customer_maintenance_history_report",
                        "slug": "customer_maintenance_history_report",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ServiceJob",
                    "Client"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`jobs[]`, `totalRows`, `clients[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "jobs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/dead_stock": {
            "get": {
                "operationId": "get_api_report_dead_stock",
                "tags": [
                    "Reports"
                ],
                "summary": "Dead stock report",
                "description": "Products with stock on hand but no movement for the chosen period, with days since last movement, frozen value and a category breakdown.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@deadStock",
                "x-source": "app/Http/Controllers/ReportController.php#L9497-L9774",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Dead_Stock_Report",
                        "slug": "Dead_Stock_Report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Brand",
                    "Category"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "brand_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Brand filter."
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category filter."
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                30,
                                60,
                                90,
                                180,
                                365
                            ]
                        },
                        "description": "Days without movement (default 90)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{product_id, product_variant_id, code, product_name, variant_name, on_hand, last_movement_at, days_since_last_movement, status}], totalRows, summary, top_frozen, by_category, range, brands, categories}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product_id": {
                                            "type": "integer"
                                        },
                                        "product_variant_id": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "code": {},
                                        "product_name": {},
                                        "variant_name": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "on_hand": {
                                            "type": "number"
                                        },
                                        "last_movement_at": {
                                            "type": "string"
                                        },
                                        "days_since_last_movement": {
                                            "type": "integer"
                                        },
                                        "status": {
                                            "type": "string"
                                        },
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "top_frozen": {},
                                        "by_category": {},
                                        "page": {
                                            "type": "integer"
                                        },
                                        "perPage": {
                                            "type": "integer"
                                        },
                                        "range": {
                                            "type": "object",
                                            "properties": {
                                                "from": {
                                                    "type": "integer"
                                                },
                                                "to": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/deposits_report": {
            "get": {
                "operationId": "get_api_report_deposits_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Deposits report",
                "description": "Deposits in the range with account, category, amount and date, plus KPIs (count, total) and a daily series. Defaults to the last 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@deposits_report",
                "x-source": "app/Http/Controllers/ReportController.php#L7593-L7697",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "deposits_report",
                        "slug": "deposits_report",
                        "policy": "DepositPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Deposit"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{reports: [], totalRows, kpis, timeseries}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "reports": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "kpis": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/discount_summary": {
            "get": {
                "operationId": "get_api_report_discount_summary",
                "tags": [
                    "Reports"
                ],
                "summary": "Discount summary",
                "description": "Per-sale discount breakdown: line discounts, manual header discount and loyalty-points discount, with a total and time series.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@discountSummary",
                "x-source": "app/Http/Controllers/ReportController.php#L9981-L10168",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "discount_summary_report",
                        "slug": "discount_summary_report",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{sale_id, date_time, user_name, total_discount, line_discount, header_manual_discount, header_points_discount}], totalRows, overall_total, timeseries}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sale_id": {
                                            "type": "integer"
                                        },
                                        "date_time": {
                                            "type": "string"
                                        },
                                        "user_name": {},
                                        "total_discount": {
                                            "type": "number"
                                        },
                                        "line_discount": {
                                            "type": "number"
                                        },
                                        "header_manual_discount": {
                                            "type": "number"
                                        },
                                        "header_points_discount": {
                                            "type": "number"
                                        },
                                        "report": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "overall_total": {
                                            "type": "number"
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/draft_invoices": {
            "get": {
                "operationId": "get_api_report_draft_invoices",
                "tags": [
                    "Reports"
                ],
                "summary": "Draft invoices",
                "description": "Sales still in draft with age in days, age buckets and per-user counts.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@draftInvoices",
                "x-source": "app/Http/Controllers/ReportController.php#L9776-L9977",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "draft_invoices_report",
                        "slug": "draft_invoices_report",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{id, Ref, date, client, warehouse, user, GrandTotal, age_days, status}], totalRows, summary, age_buckets, by_user, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "Ref": {},
                                        "date": {},
                                        "client": {},
                                        "warehouse": {},
                                        "user": {},
                                        "GrandTotal": {
                                            "type": "number"
                                        },
                                        "TaxNet": {
                                            "type": "number"
                                        },
                                        "tax_rate": {
                                            "type": "number"
                                        },
                                        "discount": {
                                            "type": "number"
                                        },
                                        "shipping": {
                                            "type": "number"
                                        },
                                        "age_days": {
                                            "type": "integer"
                                        },
                                        "status": {
                                            "type": "string",
                                            "example": "Draft"
                                        },
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "age_buckets": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_user": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/expenses_report": {
            "get": {
                "operationId": "get_api_report_expenses_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Expenses report",
                "description": "Expenses in the range with category, account, warehouse, amount and date, plus KPIs and a daily series. Defaults to the last 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@expenses_report",
                "x-source": "app/Http/Controllers/ReportController.php#L7451-L7589",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "expenses_report",
                        "slug": "expenses_report",
                        "policy": "ExpensePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Expense"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{reports: [], totalRows, kpis, timeseries, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "reports": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "kpis": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/expenses_warehouse": {
            "get": {
                "operationId": "get_api_report_expenses_warehouse",
                "tags": [
                    "Reports"
                ],
                "summary": "Expenses by warehouse list",
                "description": "Paginated expenses recorded against one warehouse (`warehouse_id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Expenses_Warehouse",
                "x-source": "app/Http/Controllers/ReportController.php#L2352-L2439",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Expense"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{expenses: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "expenses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/expiry": {
            "get": {
                "operationId": "get_api_report_expiry",
                "tags": [
                    "Reports"
                ],
                "summary": "Expiry report (pharmacy)",
                "description": "Batches grouped by expiry bucket (expired / near / valid) with KPIs per bucket and value at risk. `near` means within `expiry_warning_days` from settings. Returns `supported: false` when batch tables are missing.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@expiryReport",
                "x-source": "app/Http/Controllers/ReportController.php#L11170-L11363",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "Setting",
                    "UserWarehouse",
                    "ProductBatch",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "expiry_window",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "expired",
                                "near",
                                "valid",
                                "expired_or_near",
                                "all"
                            ]
                        },
                        "description": "Bucket filter (default `expired_or_near`)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{batches: [{id, batch_no, product_name, warehouse_name, expiry_date, qty, unit_cost, value, days_to_expiry, expiry_bucket}], totalRows, warehouses, kpis: {expired, near, valid, expired_value, near_value}, expiry_warning_days, supported}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "batches": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "kpis": {
                                            "type": "object",
                                            "properties": {
                                                "expired": {
                                                    "type": "integer"
                                                },
                                                "near": {
                                                    "type": "integer"
                                                },
                                                "valid": {
                                                    "type": "integer"
                                                },
                                                "expired_value": {
                                                    "type": "number"
                                                },
                                                "near_value": {
                                                    "type": "number"
                                                }
                                            }
                                        },
                                        "expiry_warning_days": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "supported": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {
                                            "type": "integer"
                                        },
                                        "batch_no": {
                                            "type": "string"
                                        },
                                        "product_id": {
                                            "type": "integer"
                                        },
                                        "product_name": {},
                                        "product_code": {},
                                        "generic_name": {},
                                        "strength": {},
                                        "dosage_form": {},
                                        "variant_name": {},
                                        "warehouse_id": {
                                            "type": "integer"
                                        },
                                        "warehouse_name": {},
                                        "expiry_date": {},
                                        "mfg_date": {
                                            "type": "string"
                                        },
                                        "qty": {
                                            "type": "number"
                                        },
                                        "unit_cost": {},
                                        "value": {},
                                        "status": {
                                            "type": "string"
                                        },
                                        "days_to_expiry": {},
                                        "expiry_bucket": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Error"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_adjustment_by_product": {
            "get": {
                "operationId": "get_api_report_get_adjustment_by_product",
                "tags": [
                    "Reports"
                ],
                "summary": "Adjustment lines for a product",
                "description": "Adjustment lines for one product (`id`): reference, date, warehouse, type (add/sub) and quantity.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_adjustment_by_product",
                "x-source": "app/Http/Controllers/ReportController.php#L5348-L5459",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "AdjustmentDetail",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product ID."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{adjustments: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "adjustments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_adjustment_by_user": {
            "get": {
                "operationId": "get_api_report_get_adjustment_by_user",
                "tags": [
                    "Reports"
                ],
                "summary": "Adjustments by user list",
                "description": "Stock adjustments created by one user (`id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_adjustment_by_user",
                "x-source": "app/Http/Controllers/ReportController.php#L4147-L4213",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Adjustment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "User ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{adjustments: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "adjustments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_last_sales": {
            "get": {
                "operationId": "get_api_report_get_last_sales",
                "tags": [
                    "Reports"
                ],
                "summary": "Last sales",
                "description": "The most recent sales (with customer and details) visible to the caller, for the dashboard widget.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Get_last_Sales",
                "x-source": "app/Http/Controllers/ReportController.php#L64-L102",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Sale"
                ],
                "responses": {
                    "200": {
                        "description": "Array of sale rows.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_purchase_return_by_product": {
            "get": {
                "operationId": "get_api_report_get_purchase_return_by_product",
                "tags": [
                    "Reports"
                ],
                "summary": "Purchase-return lines for a product",
                "description": "Purchase-return lines for one product (`id`) with reference, date, supplier, quantity, unit and cost.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_purchase_return_by_product",
                "x-source": "app/Http/Controllers/ReportController.php#L4804-L4940",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "PurchaseReturnDetails",
                    "Unit",
                    "Product",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product ID."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases_return: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases_return": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_purchase_return_by_user": {
            "get": {
                "operationId": "get_api_report_get_purchase_return_by_user",
                "tags": [
                    "Reports"
                ],
                "summary": "Purchase returns by user list",
                "description": "Purchase returns created by one user (`id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_purchase_return_by_user",
                "x-source": "app/Http/Controllers/ReportController.php#L3982-L4060",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PurchaseReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "User ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases_return: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases_return": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_purchases_by_product": {
            "get": {
                "operationId": "get_api_report_get_purchases_by_product",
                "tags": [
                    "Reports"
                ],
                "summary": "Purchase lines for a product",
                "description": "Purchase lines for one product (`id`) with reference, date, supplier, warehouse, quantity, unit and cost.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_purchases_by_product",
                "x-source": "app/Http/Controllers/ReportController.php#L4671-L4800",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "PurchaseDetail",
                    "Unit",
                    "Product",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product ID."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_purchases_by_user": {
            "get": {
                "operationId": "get_api_report_get_purchases_by_user",
                "tags": [
                    "Reports"
                ],
                "summary": "Purchases by user list",
                "description": "Purchases created by one user (`id`) with reference, supplier, total, paid and status.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_purchases_by_user",
                "x-source": "app/Http/Controllers/ReportController.php#L3821-L3898",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Purchase"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "User ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_quotations_by_product": {
            "get": {
                "operationId": "get_api_report_get_quotations_by_product",
                "tags": [
                    "Reports"
                ],
                "summary": "Quotation lines for a product",
                "description": "Quotation lines for one product (`id`) with reference, date, customer, quantity and price.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_quotations_by_product",
                "x-source": "app/Http/Controllers/ReportController.php#L4533-L4666",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "QuotationDetail",
                    "Unit",
                    "Product",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product ID."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{quotations: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "quotations": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_quotations_by_user": {
            "get": {
                "operationId": "get_api_report_get_quotations_by_user",
                "tags": [
                    "Reports"
                ],
                "summary": "Quotations by user list",
                "description": "Quotations created by one user (`id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_quotations_by_user",
                "x-source": "app/Http/Controllers/ReportController.php#L3743-L3817",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Quotation"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "User ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{quotations: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "quotations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_sales_by_product": {
            "get": {
                "operationId": "get_api_report_get_sales_by_product",
                "tags": [
                    "Reports"
                ],
                "summary": "Sales lines for a product",
                "description": "Sale lines for one product (`id`) with reference, date, customer, warehouse, quantity, unit and price.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_sales_by_product",
                "x-source": "app/Http/Controllers/ReportController.php#L4396-L4529",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "SaleDetail",
                    "Unit",
                    "Product",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product ID."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_sales_by_user": {
            "get": {
                "operationId": "get_api_report_get_sales_by_user",
                "tags": [
                    "Reports"
                ],
                "summary": "Sales by user list",
                "description": "Sales created by one user (`id`) with reference, customer, total, paid and status.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_sales_by_user",
                "x-source": "app/Http/Controllers/ReportController.php#L3659-L3739",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "User ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_sales_return_by_product": {
            "get": {
                "operationId": "get_api_report_get_sales_return_by_product",
                "tags": [
                    "Reports"
                ],
                "summary": "Sale-return lines for a product",
                "description": "Sale-return lines for one product (`id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_sales_return_by_product",
                "x-source": "app/Http/Controllers/ReportController.php#L5074-L5214",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "SaleReturnDetails",
                    "Unit",
                    "Product",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product ID."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales_return: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales_return": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_sales_return_by_user": {
            "get": {
                "operationId": "get_api_report_get_sales_return_by_user",
                "tags": [
                    "Reports"
                ],
                "summary": "Sale returns by user list",
                "description": "Sale returns created by one user (`id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_sales_return_by_user",
                "x-source": "app/Http/Controllers/ReportController.php#L3902-L3978",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SaleReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "User ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales_return: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales_return": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_transfer_by_product": {
            "get": {
                "operationId": "get_api_report_get_transfer_by_product",
                "tags": [
                    "Reports"
                ],
                "summary": "Transfer lines for a product",
                "description": "Transfer lines for one product (`id`) with reference, date, source and destination warehouse and quantity.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_transfer_by_product",
                "x-source": "app/Http/Controllers/ReportController.php#L5219-L5344",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "TransferDetail",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product ID."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{transfers: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "transfers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/get_transfer_by_user": {
            "get": {
                "operationId": "get_api_report_get_transfer_by_user",
                "tags": [
                    "Reports"
                ],
                "summary": "Transfers by user list",
                "description": "Stock transfers created by one user (`id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@get_transfer_by_user",
                "x-source": "app/Http/Controllers/ReportController.php#L4064-L4143",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Transfer"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "User ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{transfers: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "transfers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/inactive_customers": {
            "get": {
                "operationId": "get_api_report_inactive_customers",
                "tags": [
                    "Reports"
                ],
                "summary": "Inactive customers",
                "description": "Customers with no sale in the last `period` days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@inactiveCustomers",
                "x-source": "app/Http/Controllers/ReportController.php#L9182-L9309",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "inactive_customers_report",
                        "slug": "inactive_customers_report",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                30,
                                60,
                                90
                            ]
                        },
                        "description": "Inactivity window (default 30)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{id, name, phone, last_sale_at, days_inactive}], totalRows, stats, chart}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "chart": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/internal_location_report": {
            "get": {
                "operationId": "get_api_report_internal_location_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Internal location report",
                "description": "Stock by internal location (bin/shelf) within a warehouse: product, location, quantity. Requires `internal_location_report`.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Internal_Location_Report",
                "x-source": "app/Http/Controllers/ReportController.php#L1773-L1864",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "internal_location_report",
                        "slug": "internal_location_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{rows: [], totalRows, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/inventory_valuation_summary": {
            "get": {
                "operationId": "get_api_report_inventory_valuation_summary",
                "tags": [
                    "Reports"
                ],
                "summary": "Inventory valuation summary",
                "description": "Stock on hand × cost per product with totals, top products by value and per-warehouse values. Computed sort fields (`stock_hand`, `cost`, `inventory_value`) are sorted in memory.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@inventory_valuation_summary",
                "x-source": "app/Http/Controllers/ReportController.php#L6749-L6985",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "inventory_valuation",
                        "slug": "inventory_valuation",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Product",
                    "ProductVariant",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{reports: [{product, stock_hand, cost, inventory_value}], totalRows, summary, top_products, warehouse_values, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "reports": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "top_products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouse_values": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/negative_stock": {
            "get": {
                "operationId": "get_api_report_negative_stock",
                "tags": [
                    "Reports"
                ],
                "summary": "Negative stock report",
                "description": "Product/warehouse rows whose quantity is below zero, with the worst products and per-warehouse totals.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@negative_stock_report",
                "x-source": "app/Http/Controllers/ReportController.php#L4944-L5069",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "negative_stock_report",
                        "slug": "negative_stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{rows: [{product, warehouse, quantity}], totalRows, summary, worst_products, by_warehouse, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {
                                            "type": "string"
                                        },
                                        "units_short": {
                                            "type": "number"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "summary": {},
                                        "worst_products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_warehouse": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/product_purchases_report": {
            "get": {
                "operationId": "get_api_report_product_purchases_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Product purchases report",
                "description": "Purchase lines in the range with product, supplier, warehouse, quantity and cost; includes the supplier and warehouse lists for the filter bar. Defaults to the last 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@product_purchases_report",
                "x-source": "app/Http/Controllers/ReportController.php#L6519-L6720",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_purchases_report",
                        "slug": "product_purchases_report",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "PurchaseDetail",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Warehouse",
                    "Provider"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "provider_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier filter."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases: [], totalRows, suppliers, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/product_report": {
            "get": {
                "operationId": "get_api_report_product_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Product sales performance",
                "description": "Per-product quantity sold and revenue in the range with stats and a chart series.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@product_report",
                "x-source": "app/Http/Controllers/ReportController.php#L5630-L5856",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_report",
                        "slug": "product_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Product",
                    "SaleDetail",
                    "Unit"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{products: [{id, code, name, total_qty, total_amount}], stats, chart, totalRows, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "chart": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/product_sales_report": {
            "get": {
                "operationId": "get_api_report_product_sales_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Product sales report",
                "description": "Sales lines for products in the range with customer/warehouse filters.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@product_sales_report",
                "x-source": "app/Http/Controllers/ReportController.php#L6053-L6252",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_sales_report",
                        "slug": "product_sales_report",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "SaleDetail",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Warehouse",
                    "Client"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales: [], totalRows, customers, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/products_sold_summary": {
            "get": {
                "operationId": "get_api_report_products_sold_summary",
                "tags": [
                    "Reports"
                ],
                "summary": "Products sold summary (day report)",
                "description": "Products sold grouped by category with quantity and amount, totals, and company/meta blocks for printing. Defaults to today rather than 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@products_sold_summary",
                "x-source": "app/Http/Controllers/ReportController.php#L6256-L6515",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "products_sold_summary",
                        "slug": "products_sold_summary",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "UserWarehouse",
                    "CashRegister",
                    "Warehouse",
                    "User",
                    "Category",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "SortField",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sort column."
                    },
                    {
                        "name": "SortType",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`asc` or `desc`."
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (default today)."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product name/code search."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Sale status filter."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (default today)."
                    },
                    {
                        "name": "user_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Seller filter."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{categories: [{name, products: [{name, qty, amount}]}], totals, meta, company, warehouses, users, categories_list, currency, totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "quantity": {
                                                    "type": "number"
                                                },
                                                "total": {
                                                    "type": "number"
                                                },
                                                "items": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "from": {},
                                                "to": {},
                                                "till": {},
                                                "sales_person": {},
                                                "customer_count": {
                                                    "type": "integer"
                                                },
                                                "transaction_count": {
                                                    "type": "integer"
                                                },
                                                "day_status": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "printed_by": {}
                                            }
                                        },
                                        "company": {
                                            "type": "object",
                                            "properties": {
                                                "name": {},
                                                "address": {},
                                                "phone": {},
                                                "email": {}
                                            }
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "users": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories_list": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "currency": {},
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/profit/{dimension}": {
            "get": {
                "operationId": "get_api_report_profit_dimension",
                "tags": [
                    "Reports"
                ],
                "summary": "Profit analysis by dimension",
                "description": "Revenue, cost and profit grouped by the chosen dimension. Line revenue is `sale_details.total`; line cost is `quantity × (variant cost or product cost)`. KPIs and the chart cover the whole filtered set while rows are paginated. Default sort is `profit` descending.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ProfitReportController@index",
                "x-source": "app/Http/Controllers/ProfitReportController.php#L23-L149",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_profit",
                        "slug": "Reports_profit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "name": "dimension",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "product",
                                "category",
                                "unit",
                                "customer",
                                "date",
                                "warehouse"
                            ]
                        },
                        "description": "Grouping dimension."
                    },
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{rows: [{key, name, revenue, cost, profit, margin}], totalRows, kpis, chart, warehouses, from, to}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "kpis": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "chart": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "from": {},
                                        "to": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/profit_and_loss": {
            "get": {
                "operationId": "get_api_report_profit_and_loss",
                "tags": [
                    "Reports"
                ],
                "summary": "Profit and loss",
                "description": "Revenue, cost of goods, returns, expenses, payments in/out (including opening balances and service-job payments) and net profit for the range, plus a daily series.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@ProfitAndLoss",
                "x-source": "app/Http/Controllers/ReportController.php#L2552-L2785",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_profit",
                        "slug": "Reports_profit",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Sale",
                    "Purchase",
                    "SaleReturn",
                    "PurchaseReturn",
                    "PaymentSale",
                    "PaymentSaleReturns",
                    "PaymentPurchaseReturns",
                    "PaymentPurchase",
                    "Expense",
                    "PaymentOpeningBalance",
                    "ProviderPaymentOpeningBalance",
                    "ServiceJobPayment"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (required)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (required)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{data: [{label, value}], warehouses, timeseries}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/provider": {
            "get": {
                "operationId": "get_api_report_provider",
                "tags": [
                    "Reports"
                ],
                "summary": "Suppliers report",
                "description": "Per-supplier totals: purchase count, total amount, paid and due, plus stats and a chart series.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Providers_Report",
                "x-source": "app/Http/Controllers/ReportController.php#L1306-L1420",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_suppliers",
                        "slug": "Reports_suppliers",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Provider"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{id, name, phone, total_purchase, total_amount, total_paid, due}], totalRows, stats, chart}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "chart": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/provider/{id}": {
            "get": {
                "operationId": "get_api_report_provider_id",
                "tags": [
                    "Reports"
                ],
                "summary": "Supplier report header",
                "description": "Totals for one supplier: purchase count, total amount, paid, due and returns.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Provider_Report_detail",
                "x-source": "app/Http/Controllers/ReportController.php#L297-L327",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_suppliers",
                        "slug": "Reports_suppliers",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Supplier ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: {total_purchase, total_amount, total_paid, due, total_returns...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/provider_payments": {
            "get": {
                "operationId": "get_api_report_provider_payments",
                "tags": [
                    "Reports"
                ],
                "summary": "Supplier payments list",
                "description": "Paginated payments sent to one supplier (`id`) with purchase reference, date, method and amount.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Payments_Provider",
                "x-source": "app/Http/Controllers/ReportController.php#L1504-L1587",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_suppliers",
                        "slug": "Reports_suppliers",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{payments: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/provider_pdf/{id}": {
            "get": {
                "operationId": "get_api_report_provider_pdf_id",
                "tags": [
                    "Reports"
                ],
                "summary": "Supplier statement PDF",
                "description": "PDF listing the supplier's unpaid/partially paid purchases with the outstanding balance.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@download_report_provider_pdf",
                "x-source": "app/Http/Controllers/ReportController.php#L5547-L5626",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_suppliers",
                        "slug": "Reports_suppliers",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-models": [
                    "Provider",
                    "Purchase",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Supplier ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/provider_purchases": {
            "get": {
                "operationId": "get_api_report_provider_purchases",
                "tags": [
                    "Reports"
                ],
                "summary": "Supplier purchases list",
                "description": "Paginated purchases of one supplier (`id`) with reference, date, total, paid, due and status.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Purchases_Provider",
                "x-source": "app/Http/Controllers/ReportController.php#L1424-L1500",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_suppliers",
                        "slug": "Reports_suppliers",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Purchase"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/provider_returns": {
            "get": {
                "operationId": "get_api_report_provider_returns",
                "tags": [
                    "Reports"
                ],
                "summary": "Supplier returns list",
                "description": "Paginated purchase returns of one supplier (`id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Returns_Provider",
                "x-source": "app/Http/Controllers/ReportController.php#L1591-L1675",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_suppliers",
                        "slug": "Reports_suppliers",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "PurchaseReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{returns_supplier: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "returns_supplier": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/purchases": {
            "get": {
                "operationId": "get_api_report_purchases",
                "tags": [
                    "Reports"
                ],
                "summary": "Purchases report",
                "description": "Paginated purchases with filters, summary, daily time series, payment-status breakdown and the supplier/warehouse lists for the filter bar.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Report_Purchases",
                "x-source": "app/Http/Controllers/ReportController.php#L661-L842",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "ReportPurchases",
                        "slug": "Reports_purchase",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "statut",
                    "provider_id",
                    "payment_statut",
                    "warehouse_id"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Purchase",
                    "Provider",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact purchase reference."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (default: 29 days ago)."
                    },
                    {
                        "name": "payment_statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Payment status: `paid`, `partial`, `unpaid`."
                    },
                    {
                        "name": "provider_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Supplier filter."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "Purchase status: `received`, `pending`, `ordered`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (default: today)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases: [], totalRows, summary, timeseries, payment_breakdown, suppliers, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "summary": {},
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_breakdown": {},
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/purchases_warehouse": {
            "get": {
                "operationId": "get_api_report_purchases_warehouse",
                "tags": [
                    "Reports"
                ],
                "summary": "Purchases by warehouse list",
                "description": "Paginated purchases received into one warehouse (`warehouse_id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Purchases_Warehouse",
                "x-source": "app/Http/Controllers/ReportController.php#L1965-L2045",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Purchase"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{purchases: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/quotations_warehouse": {
            "get": {
                "operationId": "get_api_report_quotations_warehouse",
                "tags": [
                    "Reports"
                ],
                "summary": "Quotations by warehouse list",
                "description": "Paginated quotations issued from one warehouse (`warehouse_id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Quotations_Warehouse",
                "x-source": "app/Http/Controllers/ReportController.php#L2049-L2136",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Quotation"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{quotations: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "quotations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/report_transactions": {
            "get": {
                "operationId": "get_api_report_report_transactions",
                "tags": [
                    "Reports"
                ],
                "summary": "Transactions report",
                "description": "Unified ledger of payments: sale, purchase, sale-return, purchase-return payments, opening balances and expenses, with totals per type and filter lists.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@report_transactions",
                "x-source": "app/Http/Controllers/ReportController.php#L7699-L8070",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report_transactions",
                        "slug": "report_transactions",
                        "policy": "PaymentSalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "PaymentSale",
                    "PaymentOpeningBalance",
                    "PaymentSaleReturns",
                    "PaymentPurchase",
                    "ProviderPaymentOpeningBalance",
                    "PaymentPurchaseReturns",
                    "Client",
                    "Provider",
                    "Sale",
                    "Purchase",
                    "PaymentMethod",
                    "Expense"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "payment_method_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Payment method filter."
                    },
                    {
                        "name": "provider_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Supplier filter."
                    },
                    {
                        "name": "purchase_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Purchase filter."
                    },
                    {
                        "name": "sale_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sale filter."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{payments: [{date, Ref, type, client_name, payment_method, montant, account_name, user_name}], totalRows, sale_total, purchase_total, sale_return_total, purchase_return_total, expense_total, payment_summary, sales, clients, payment_methods, suppliers, purchases}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "date": {},
                                        "Ref": {},
                                        "Ref_Sale": {
                                            "type": "string"
                                        },
                                        "sale_id": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "client_name": {},
                                        "payment_method": {},
                                        "montant": {},
                                        "account_name": {},
                                        "user_name": {},
                                        "type": {
                                            "type": "string",
                                            "example": "purchase_return"
                                        },
                                        "created_at": {},
                                        "purchase_id": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "purchase_total": {
                                            "type": "number"
                                        },
                                        "sale_total": {
                                            "type": "number"
                                        },
                                        "sale_return_total": {
                                            "type": "number"
                                        },
                                        "purchase_return_total": {
                                            "type": "number"
                                        },
                                        "expense_total": {
                                            "type": "number"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_summary": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/return_ratio_report": {
            "get": {
                "operationId": "get_api_report_return_ratio_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Return ratio",
                "description": "Sales vs sale returns and purchases vs purchase returns (counts, amounts and ratios) for the range. Defaults to all time.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@return_ratio_report",
                "x-source": "app/Http/Controllers/ReportController.php#L3241-L3307",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "return_ratio_report",
                        "slug": "return_ratio_report",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Sale",
                    "SaleReturn",
                    "Purchase",
                    "PurchaseReturn"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{data: {sales, sale_returns, sale_return_ratio, purchases, purchase_returns, purchase_return_ratio}, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "sales_sum": {},
                                                "returns_sales_sum": {},
                                                "sales_return_ratio_pct": {},
                                                "purchases_sum": {},
                                                "returns_purchases_sum": {},
                                                "purchase_return_ratio_pct": {}
                                            }
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/returns_purchase_warehouse": {
            "get": {
                "operationId": "get_api_report_returns_purchase_warehouse",
                "tags": [
                    "Reports"
                ],
                "summary": "Purchase returns by warehouse list",
                "description": "Paginated purchase returns shipped from one warehouse (`warehouse_id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Returns_Purchase_Warehouse",
                "x-source": "app/Http/Controllers/ReportController.php#L2245-L2348",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "PurchaseReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{returns_purchase: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "returns_purchase": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/returns_sale_warehouse": {
            "get": {
                "operationId": "get_api_report_returns_sale_warehouse",
                "tags": [
                    "Reports"
                ],
                "summary": "Sale returns by warehouse list",
                "description": "Paginated sale returns received into one warehouse (`warehouse_id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Returns_Sale_Warehouse",
                "x-source": "app/Http/Controllers/ReportController.php#L2140-L2240",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "SaleReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{returns_sale: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "returns_sale": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/sale_products_details": {
            "get": {
                "operationId": "get_api_report_sale_products_details",
                "tags": [
                    "Reports"
                ],
                "summary": "Sold product lines",
                "description": "Line-level sales detail (one row per sale line) with product, quantity, price, customer, seller and warehouse filters.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@sale_products_details",
                "x-source": "app/Http/Controllers/ReportController.php#L5860-L6049",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "product_report",
                        "slug": "product_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "SaleDetail",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Client",
                    "User",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sale reference."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product filter."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "user_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Seller filter."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales: [], totalRows, customers, warehouses, users}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "users": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/sales": {
            "get": {
                "operationId": "get_api_report_sales",
                "tags": [
                    "Reports"
                ],
                "summary": "Sales report",
                "description": "Paginated sales with filters plus a summary (count, grand total, paid, due), a daily time series, a payment-status breakdown and the seller/customer/warehouse lists used by the filter bar. Time-of-day filtering is available through `start_time`/`end_time`.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Report_Sales",
                "x-source": "app/Http/Controllers/ReportController.php#L846-L1076",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Reports_sales",
                        "slug": "Reports_sales",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "statut",
                    "client_id",
                    "payment_statut",
                    "warehouse_id"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Sale",
                    "Client",
                    "User",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact sale reference."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Customer filter."
                    },
                    {
                        "name": "end_time",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Latest time of day (`HH:MM`)."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (default: 29 days ago)."
                    },
                    {
                        "name": "payment_statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Payment status: `paid`, `partial`, `unpaid`."
                    },
                    {
                        "name": "start_time",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Earliest time of day (`HH:MM`)."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "Sale status: `completed`, `pending`, `ordered`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (default: today)."
                    },
                    {
                        "name": "user_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Seller (user) filter."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales: [], totalRows, summary, timeseries: [{date, total}], payment_breakdown, sellers, customers, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "summary": {},
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_breakdown": {},
                                        "sellers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/sales_by_brand_report": {
            "get": {
                "operationId": "get_api_report_sales_by_brand_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Sales by brand",
                "description": "Quantity and revenue sold per brand in the range with a summary, top brands and a daily series. Defaults to the last 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@sales_by_brand_report",
                "x-source": "app/Http/Controllers/ReportController.php#L8715-L8866",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report_sales_by_brand",
                        "slug": "report_sales_by_brand",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Brand"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{reports: [{name, qty, value}], totalRows, summary, top_groups, timeseries, currency}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "value": {
                                            "type": "number"
                                        },
                                        "reports": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "top_groups": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "currency": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/sales_by_category_report": {
            "get": {
                "operationId": "get_api_report_sales_by_category_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Sales by category",
                "description": "Quantity and revenue sold per category in the range with a summary, top categories and a daily series. Defaults to the last 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@sales_by_category_report",
                "x-source": "app/Http/Controllers/ReportController.php#L8561-L8712",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report_sales_by_category",
                        "slug": "report_sales_by_category",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Category"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{reports: [{name, qty, value}], totalRows, summary, top_groups, timeseries, currency}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "value": {
                                            "type": "number"
                                        },
                                        "reports": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "top_groups": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "currency": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/sales_warehouse": {
            "get": {
                "operationId": "get_api_report_sales_warehouse",
                "tags": [
                    "Reports"
                ],
                "summary": "Sales by warehouse list",
                "description": "Paginated sales made from one warehouse (`warehouse_id`).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Sales_Warehouse",
                "x-source": "app/Http/Controllers/ReportController.php#L1868-L1961",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Sale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/seller_report": {
            "get": {
                "operationId": "get_api_report_seller_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Seller (cashier) report",
                "description": "Per-seller sales totals in a date/time window, broken down by payment method. Used for shift reconciliation.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@seller_report",
                "x-source": "app/Http/Controllers/ReportController.php#L8869-L9066",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "seller_report",
                        "slug": "seller_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "User",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "end_time",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End time of day (`HH:MM`)."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "start_time",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start time of day (`HH:MM`)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{user, total_sales, total_amount, by_method: {...}}], warehouses, paymentMethods, totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "paymentMethods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/serials/available": {
            "get": {
                "operationId": "get_api_report_serials_available",
                "tags": [
                    "Serial Number Reports"
                ],
                "summary": "Available serial numbers",
                "description": "Serialised units currently in stock (status `available`) with product, warehouse and supplier.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "SerialNumberReportController@available",
                "x-source": "app/Http/Controllers/SerialNumberReportController.php#L17-L53",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "serial_numbers_report",
                        "slug": "serial_numbers_report",
                        "policy": "ProductSerialPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProductSerial"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/serials/inventory": {
            "get": {
                "operationId": "get_api_report_serials_inventory",
                "tags": [
                    "Serial Number Reports"
                ],
                "summary": "Serial inventory by product",
                "description": "Per-product counts of serialised units by status (available, sold, returned, defective…).",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "SerialNumberReportController@inventory",
                "x-source": "app/Http/Controllers/SerialNumberReportController.php#L146-L215",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "serial_numbers_report",
                        "slug": "serial_numbers_report",
                        "policy": "ProductSerialPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{product_id, name, code, available, sold, returned, defective, total}], totalRows, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/serials/movements": {
            "get": {
                "operationId": "get_api_report_serials_movements",
                "tags": [
                    "Serial Number Reports"
                ],
                "summary": "Serial movement history",
                "description": "Serial Movement History Report — every lifecycle event. /",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "SerialNumberReportController@movements",
                "x-source": "app/Http/Controllers/SerialNumberReportController.php#L99-L141",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "serial_numbers_report",
                        "slug": "serial_numbers_report",
                        "policy": "ProductSerialPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProductSerialMovement"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "action",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "purchased",
                                "sold",
                                "sale_returned",
                                "purchase_returned",
                                "status_changed",
                                "adjusted"
                            ]
                        },
                        "description": "Lifecycle event type."
                    },
                    {
                        "name": "from_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{serial_number, product, action, from_status, to_status, reference, warehouse, user, created_at}], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/serials/sold": {
            "get": {
                "operationId": "get_api_report_serials_sold",
                "tags": [
                    "Serial Number Reports"
                ],
                "summary": "Sold serial numbers",
                "description": "Units with status `sold`, with customer and sale reference.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "SerialNumberReportController@sold",
                "x-source": "app/Http/Controllers/SerialNumberReportController.php#L58-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "serial_numbers_report",
                        "slug": "serial_numbers_report",
                        "policy": "ProductSerialPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProductSerial"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/service_checklist_completion": {
            "get": {
                "operationId": "get_api_report_service_checklist_completion",
                "tags": [
                    "Service Reports"
                ],
                "summary": "Checklist completion report",
                "description": "Per checklist category/item: number of jobs, completed count and completion rate.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceReportController@checklistCompletion",
                "x-source": "app/Http/Controllers/ServiceReportController.php#L114-L186",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "checklist_completion_report",
                        "slug": "checklist_completion_report",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "ServiceTechnician",
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "job_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Job type."
                    },
                    {
                        "name": "technician_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Technician."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` and lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "integer"
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "technicians": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "job_types": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/service_jobs": {
            "get": {
                "operationId": "get_api_report_service_jobs",
                "tags": [
                    "Service Reports"
                ],
                "summary": "Service jobs report",
                "description": "Paginated job rows (client, technician, dates, amounts) with lookups `clients`, `technicians`, `job_types`, `statuses`. Sortable `id, scheduled_date, status, job_type`.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceReportController@serviceJobs",
                "x-source": "app/Http/Controllers/ServiceReportController.php#L15-L111",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "service_jobs_report",
                        "slug": "service_jobs_report",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ServiceJob",
                    "Client",
                    "ServiceTechnician"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled from."
                    },
                    {
                        "name": "job_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Type."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "technician_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Technician."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "technicians": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "job_types": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "statuses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/stock": {
            "get": {
                "operationId": "get_api_report_stock",
                "tags": [
                    "Reports"
                ],
                "summary": "Stock report",
                "description": "Current quantity per product (and variant) per warehouse with cost/price values, a summary, category units and the low-stock list.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@stock_Report",
                "x-source": "app/Http/Controllers/ReportController.php#L4217-L4392",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "stock_report",
                        "slug": "stock_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{product_id, code, name, category, unit, quantity, stock_alert, cost, price}], totalRows, summary, category_units, low_stock, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "category_units": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "low_stock": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/stock_adjustment": {
            "get": {
                "operationId": "get_api_report_stock_adjustment",
                "tags": [
                    "Reports"
                ],
                "summary": "Stock adjustment report",
                "description": "Adjustment documents in the range (default: last 7 days) with added/subtracted quantity, net quantity and value at cost and sale price.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@stockAdjustmentReport",
                "x-source": "app/Http/Controllers/ReportController.php#L10913-L11054",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Stock_Adjustment_Report",
                        "slug": "Stock_Adjustment_Report",
                        "policy": "AdjustmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "AdjustmentDetail"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{data: {rows: [{adj_id, ref, date, warehouse, qty, net_qty, purchase_cost, sale_price}], totalRows}, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "adj_id": {
                                            "type": "integer"
                                        },
                                        "ref": {},
                                        "date": {
                                            "type": "string"
                                        },
                                        "warehouse": {},
                                        "qty": {
                                            "type": "number"
                                        },
                                        "net_qty": {
                                            "type": "number"
                                        },
                                        "purchase_cost": {
                                            "type": "number"
                                        },
                                        "sale_price": {
                                            "type": "number"
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "kpis": {
                                                    "type": "object",
                                                    "properties": {
                                                        "adjustments_count": {
                                                            "type": "integer"
                                                        },
                                                        "qty_added": {
                                                            "type": "number"
                                                        },
                                                        "qty_removed": {
                                                            "type": "number"
                                                        },
                                                        "net_qty": {}
                                                    }
                                                },
                                                "timeseries": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "byType": {},
                                                "rows": {
                                                    "type": "integer"
                                                },
                                                "totalRows": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/stock_aging": {
            "get": {
                "operationId": "get_api_report_stock_aging",
                "tags": [
                    "Reports"
                ],
                "summary": "Stock aging report",
                "description": "How long current stock has been sitting since its last inbound movement, bucketed by age. Default buckets are `0-30,31-60,61-90,91-180,181+`; pass `buckets` as comma-separated upper bounds to customise.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@stockAging",
                "x-source": "app/Http/Controllers/ReportController.php#L10398-L10689",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Stock_Aging_Report",
                        "slug": "Stock_Aging_Report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "brand_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Brand filter."
                    },
                    {
                        "name": "buckets",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Comma-separated day cut-offs (e.g. `30,60,90,180`)."
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category filter."
                    },
                    {
                        "name": "dimension",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "product",
                                "variant"
                            ]
                        },
                        "description": "Group rows by product or by variant."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{product_id, product_variant_id, code, product_name, variant_name, on_hand, last_inbound_at, age_days, age_bucket}], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product_id": {
                                            "type": "integer"
                                        },
                                        "product_variant_id": {
                                            "type": "integer"
                                        },
                                        "code": {},
                                        "product_name": {},
                                        "variant_name": {},
                                        "on_hand": {
                                            "type": "number"
                                        },
                                        "last_inbound_at": {
                                            "type": "string"
                                        },
                                        "age_days": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "age_bucket": {},
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/stock_aging/filters": {
            "get": {
                "operationId": "get_api_report_stock_aging_filters",
                "tags": [
                    "Reports"
                ],
                "summary": "Stock aging filter options",
                "description": "Warehouses (scoped to the caller), brands and categories for the stock-aging filter bar.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@stockAgingFilters",
                "x-source": "app/Http/Controllers/ReportController.php#L10691-L10722",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Stock_Aging_Report",
                        "slug": "Stock_Aging_Report",
                        "policy": "ProductPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{warehouses, brands, categories}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/stock_inventory_valuation": {
            "get": {
                "operationId": "get_api_report_stock_inventory_valuation",
                "tags": [
                    "Reports"
                ],
                "summary": "Stock inventory valuation (movement)",
                "description": "Per product/variant/warehouse: opening stock, purchases, sales, transfers, adjustments and closing stock for the date range, valued at cost and at price.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@stock_inventory_valuation",
                "x-source": "app/Http/Controllers/ReportController.php#L6989-L7338",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Stock_Inventory_Valuation",
                        "slug": "Stock_Inventory_Valuation",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Product",
                    "ProductVariant",
                    "product_warehouse",
                    "SaleDetail",
                    "TransferDetail",
                    "AdjustmentDetail",
                    "Unit"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{reports: [{product, variant, warehouse, opening, in, out, closing, stock_value_cost, stock_value_price}], totalRows, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "reports": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/stock_transfer": {
            "get": {
                "operationId": "get_api_report_stock_transfer",
                "tags": [
                    "Reports"
                ],
                "summary": "Stock transfer report",
                "description": "Transfers in the range (default: last 7 days). With `warehouse_id`, `direction` selects inbound, outbound or both for that warehouse.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@stockTransferReport",
                "x-source": "app/Http/Controllers/ReportController.php#L10726-L10910",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Stock_Transfer_Report",
                        "slug": "Stock_Transfer_Report",
                        "policy": "TransferPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Warehouse",
                    "TransferDetail"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all",
                                "inbound",
                                "outbound"
                            ]
                        },
                        "description": "Direction relative to `warehouse_id`."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "from_warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Source warehouse filter."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Transfer status (`completed`, `pending`, `sent`)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "to_warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Destination warehouse filter."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse the direction applies to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{data: {rows: [{transfer_id, date_time, from, to, qty, value, statut}], totalRows}, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "transfer_id": {
                                            "type": "integer"
                                        },
                                        "date_time": {
                                            "type": "string"
                                        },
                                        "from": {},
                                        "to": {},
                                        "qty": {
                                            "type": "number"
                                        },
                                        "value": {
                                            "type": "number"
                                        },
                                        "statut": {},
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "kpis": {
                                                    "type": "object",
                                                    "properties": {
                                                        "transfers_count": {
                                                            "type": "integer"
                                                        },
                                                        "lines_count": {
                                                            "type": "integer"
                                                        },
                                                        "qty_sum": {
                                                            "type": "number"
                                                        },
                                                        "value_sum": {
                                                            "type": "number"
                                                        },
                                                        "avg_items_per_transfer": {
                                                            "type": "number"
                                                        },
                                                        "avg_value_per_transfer": {
                                                            "type": "number"
                                                        }
                                                    }
                                                },
                                                "timeseries": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "routes": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "rows": {
                                                    "type": "integer"
                                                },
                                                "totalRows": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/tax_summary": {
            "get": {
                "operationId": "get_api_report_tax_summary",
                "tags": [
                    "Reports"
                ],
                "summary": "Tax summary",
                "description": "Per-sale taxable base, tax collected and effective rate, with totals and a time series.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@taxSummary",
                "x-source": "app/Http/Controllers/ReportController.php#L10170-L10288",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "tax_summary_report",
                        "slug": "tax_summary_report",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{sale_id, date_time, user_name, taxable_base, tax_collected, effective_rate}], totalRows, totals, timeseries}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sale_id": {
                                            "type": "integer"
                                        },
                                        "date_time": {
                                            "type": "string"
                                        },
                                        "user_name": {},
                                        "taxable_base": {
                                            "type": "number"
                                        },
                                        "tax_collected": {
                                            "type": "number"
                                        },
                                        "effective_rate": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "report": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "timeseries": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/top_customers": {
            "get": {
                "operationId": "get_api_report_top_customers",
                "tags": [
                    "Reports"
                ],
                "summary": "Top customers",
                "description": "Customers ranked by revenue (or number of sales) in the range, with stats and a chart series. Defaults to the last 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@report_top_customers",
                "x-source": "app/Http/Controllers/ReportController.php#L3419-L3520",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Top_customers",
                        "slug": "Top_customers",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserWarehouse",
                    "Sale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "order_by",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "amount",
                                "orders"
                            ]
                        },
                        "description": "Rank by revenue or number of sales (default `amount`)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{customers: [{id, name, total, total_sales}], totalRows, stats, chart}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "chart": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/top_products": {
            "get": {
                "operationId": "get_api_report_top_products",
                "tags": [
                    "Reports"
                ],
                "summary": "Top products",
                "description": "Products ranked by revenue, units or number of sale lines in the range, with stats and a chart series. Defaults to the last 30 days.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@report_top_products",
                "x-source": "app/Http/Controllers/ReportController.php#L3311-L3415",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Top_products",
                        "slug": "Top_products",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SaleDetail"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "order_by",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "amount",
                                "qty",
                                "orders"
                            ]
                        },
                        "description": "Rank by revenue, units or number of sale lines (default `amount`)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{products: [{id, code, name, total, total_qty, total_sales}], totalRows, stats, chart}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "chart": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/top_suppliers": {
            "get": {
                "operationId": "get_api_report_top_suppliers",
                "tags": [
                    "Reports"
                ],
                "summary": "Top suppliers",
                "description": "Suppliers ranked by purchase value in the period (defaults to the current month) with order count, quantity, value and average order value.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@topSuppliersReport",
                "x-source": "app/Http/Controllers/ReportController.php#L11057-L11161",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Top_Suppliers_Report",
                        "slug": "Top_Suppliers_Report",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date (default: first day of this month)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date (default: last day of this month)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{data: {rows: [{supplier_id, supplier, orders_count, qty_sum, value_sum, avg_value}], totalRows}, warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "supplier_id": {
                                            "type": "integer"
                                        },
                                        "supplier": {},
                                        "orders_count": {
                                            "type": "integer"
                                        },
                                        "qty_sum": {
                                            "type": "number"
                                        },
                                        "value_sum": {
                                            "type": "number"
                                        },
                                        "avg_value": {
                                            "type": "number"
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "kpis": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "topByValue": {},
                                                "topByQty": {
                                                    "type": "integer"
                                                },
                                                "rows": {
                                                    "type": "integer"
                                                },
                                                "totalRows": {
                                                    "type": "integer"
                                                },
                                                "range": {
                                                    "type": "object",
                                                    "properties": {
                                                        "from": {
                                                            "type": "string"
                                                        },
                                                        "to": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/users": {
            "get": {
                "operationId": "get_api_report_users",
                "tags": [
                    "Reports"
                ],
                "summary": "Users report",
                "description": "Per-user activity: number of sales, purchases, quotations, returns, transfers and adjustments, with a summary and activity chart.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@users_Report",
                "x-source": "app/Http/Controllers/ReportController.php#L3524-L3655",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "users_report",
                        "slug": "users_report",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "User"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{id, username, total_sales, total_purchases, ...}], totalRows, summary, activity, top_users}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "activity": {},
                                        "top_users": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/warehouse_report": {
            "get": {
                "operationId": "get_api_report_warehouse_report",
                "tags": [
                    "Reports"
                ],
                "summary": "Warehouse overview",
                "description": "Per-warehouse counts and totals of sales, purchases, sale returns and purchase returns.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Warehouse_Report",
                "x-source": "app/Http/Controllers/ReportController.php#L1705-L1770",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "UserWarehouse",
                    "Sale",
                    "Purchase",
                    "PurchaseReturn",
                    "SaleReturn",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Restrict to one warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{data: [{warehouse, sales, purchases, returns_sale, returns_purchase}], warehouses}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/warhouse_count_stock": {
            "get": {
                "operationId": "get_api_report_warhouse_count_stock",
                "tags": [
                    "Reports"
                ],
                "summary": "Warehouse stock count and value",
                "description": "Per-warehouse item count, quantity and stock value at cost and at sale price, shaped for the bar charts.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@Warhouse_Count_Stock",
                "x-source": "app/Http/Controllers/ReportController.php#L2443-L2535",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "WarehouseStock",
                        "slug": "Warehouse_report",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "UserWarehouse",
                    "product_warehouse",
                    "Warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`{stock_count, stock_value, warehouses, count_labels, count_items, count_qty, value_labels, value_price, value_cost, warehouse_names}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stock_count": {
                                            "type": "integer"
                                        },
                                        "stock_value": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count_labels": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count_items": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count_qty": {
                                            "type": "integer"
                                        },
                                        "value_labels": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "value_price": {},
                                        "value_cost": {},
                                        "warehouse_names": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/warranty_guarantee": {
            "get": {
                "operationId": "get_api_report_warranty_guarantee",
                "tags": [
                    "Reports"
                ],
                "summary": "Warranty / guarantee report",
                "description": "Sold lines carrying a warranty or guarantee date with days remaining and status (`Active`, `Expiring Soon`, `Expired`), a summary and an expiry timeline.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@warrantyGuaranteeReport",
                "x-source": "app/Http/Controllers/ReportController.php#L1083-L1302",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report_warranty",
                        "slug": "report_warranty",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SaleDetail",
                    "Client",
                    "Warehouse",
                    "UserWarehouse",
                    "Product"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sale date from."
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product filter."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "Active",
                                "Expiring Soon",
                                "Expired"
                            ]
                        },
                        "description": "Coverage status."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sale date to."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{rows: [{sale_date, Ref, product_name, quantity, client_name, warehouse_name, warranty_date, guarantee_date, days_remaining, status}], totalRows, summary, expiry_timeline, customers, warehouses, products}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "summary": {},
                                        "expiry_timeline": {},
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/report/zero_sales_products": {
            "get": {
                "operationId": "get_api_report_zero_sales_products",
                "tags": [
                    "Reports"
                ],
                "summary": "Zero-sales products",
                "description": "Products that sold nothing in the period, with last sale date and idle-days buckets. `period` accepts a day count or `all`.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "ReportController@zeroSalesProducts",
                "x-source": "app/Http/Controllers/ReportController.php#L9311-L9495",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zeroSalesProducts",
                        "slug": "zeroSalesProducts",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Product",
                    "Brand",
                    "Category"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "brand_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Brand filter."
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category filter."
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Days to look back (`30`, `60`, `90`, `180`, `365`) or `all`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{report: [{id, code, name, price, period_qty, last_sale_at, days_since_last_sale, status}], totalRows, summary, idle_buckets, by_category, brands, categories}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "code": {},
                                        "name": {},
                                        "price": {
                                            "type": "number"
                                        },
                                        "period_qty": {
                                            "type": "integer"
                                        },
                                        "last_sale_at": {
                                            "type": "string"
                                        },
                                        "days_since_last_sale": {
                                            "type": "integer"
                                        },
                                        "status": {
                                            "type": "string"
                                        },
                                        "report": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "summary": {},
                                        "idle_buckets": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "by_category": {},
                                        "brands": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/retrieve-customer": {
            "get": {
                "operationId": "get_api_retrieve_customer",
                "tags": [
                    "Stripe"
                ],
                "summary": "Retrieve saved cards (deprecated)",
                "description": "Always returns an empty list; saved-card payments are no longer supported.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "StripeController@retrieveCustomer",
                "x-source": "app/Http/Controllers/StripeController.php#L22-L28",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`data: []`, `customer_default_source: null`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "customer_default_source": {
                                            "nullable": true,
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/return_purchase_pdf/{id}": {
            "get": {
                "operationId": "get_api_return_purchase_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Purchase return PDF",
                "description": "A4 purchase-return document with the original purchase reference, supplier block, returned lines (with batches) and totals in the document currency. Public route (no token).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "PurchasesReturnController@Return_pdf",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L1339-L1463",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "PurchaseReturn",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase return ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/return_sale_pdf/{id}": {
            "get": {
                "operationId": "get_api_return_sale_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Sale return PDF",
                "description": "A4 sale-return document (credit note) with the original sale reference, customer block, returned lines (with batches) and totals in the document currency. Public route (no token).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "SalesReturnController@Return_pdf",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L1281-L1405",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "SaleReturn",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale return ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/returns/purchase": {
            "get": {
                "operationId": "get_api_returns_purchase",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "List purchase returns",
                "description": "Paginated purchase returns scoped to the caller's warehouses and record view. Rows: `id, date, Ref, statut, provider_name, purchase_ref, purchase_id, warehouse_name, GrandTotal, paid_amount, due, payment_status`. Also returns `suppliers`, `warehouses`, `purchases`, `accounts`, `payment_methods`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@index",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L36-L177",
                "x-route-name": "purchase.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchase_Returns_view",
                        "policy": "PurchaseReturnPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "statut",
                    "provider_id",
                    "payment_statut",
                    "warehouse_id",
                    "date",
                    "purchase_id"
                ],
                "x-models": [
                    "UserWarehouse",
                    "PurchaseReturn",
                    "Provider",
                    "Purchase",
                    "Account",
                    "PaymentMethod",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact date."
                    },
                    {
                        "name": "payment_statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "`paid`, `partial`, `unpaid`."
                    },
                    {
                        "name": "provider_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Supplier id."
                    },
                    {
                        "name": "purchase_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Original purchase id."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "`completed` or `pending`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchase_returns[]`, `totalRows`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "purchase_returns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "suppliers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_returns_purchase",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Create a purchase return",
                "description": "Creates the return with its lines. When `statut` is `completed`, each line's quantity (× purchase-unit operator) is **removed** from the warehouse stock, batches are debited and serials in `imei_number` are marked returned to supplier. Inherits the parent purchase's currency snapshot.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@store",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L181-L293",
                "x-route-name": "purchase.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchase_Returns_add",
                        "policy": "PurchaseReturnPolicy"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "Purchase",
                    "Unit",
                    "PurchaseReturnDetails",
                    "product_warehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Lines: `{product_id, product_variant_id, quantity, purchase_unit_id, Unit_cost, tax_percent, tax_method, discount, discount_Method, subtotal, imei_number, batches?}`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "purchase_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Original purchase id (optional)."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`completed` or `pending`.",
                                        "type": "string"
                                    },
                                    "supplier_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Supplier id."
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                }
                            },
                            "example": {
                                "supplier_id": 2,
                                "warehouse_id": 1,
                                "purchase_id": 12,
                                "date": "2026-09-08",
                                "statut": "completed",
                                "tax_rate": 0,
                                "TaxNet": 0,
                                "discount": 0,
                                "shipping": 0,
                                "GrandTotal": 85,
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 10,
                                        "purchase_unit_id": 1,
                                        "Unit_cost": 8.5,
                                        "tax_percent": 0,
                                        "tax_method": "1",
                                        "discount": 0,
                                        "discount_Method": "2",
                                        "subtotal": 85,
                                        "imei_number": null
                                    }
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/purchase/create": {
            "get": {
                "operationId": "get_api_returns_purchase_create",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "(Not implemented) Create-form lookups",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/returns/purchase/create_purchase_return/{id}`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@create",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L799-L804",
                "x-route-name": "purchase.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/purchase/create_purchase_return/{id}": {
            "get": {
                "operationId": "get_api_returns_purchase_create_purchase_return_id",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Pre-fill a return from a purchase",
                "description": "Loads the purchase lines in *return form* shape: `purchase_return` defaults (`supplier_id, warehouse_id, purchase_id, purchase_ref, statut completed, zeros`) and `details[]` (`product_id, product_variant_id, code, name, quantity purchased, purchase_unit_id, Unit_cost, tax fields, discount fields, subtotal, stock, imei_number`).",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@create_purchase_return",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L817-L953",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchase_Returns_add",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchase_return` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchase_return": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/purchase/delete/by_selection": {
            "post": {
                "operationId": "post_api_returns_purchase_delete_by_selection",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Delete several purchase returns",
                "description": "Deletes each return in `selectedIds` with the same rules.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@delete_by_selection",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L668-L795",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Purchase_Returns_delete",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "UserWarehouse",
                    "PurchaseReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "PaymentPurchaseReturns",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of purchase return ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/purchase/edit_purchase_return/{id}/{purchase_id}": {
            "get": {
                "operationId": "get_api_returns_purchase_edit_purchase_return_id_purchase_id",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Get a purchase return for editing",
                "description": "Form-shaped payload: `purchase_return` header (`supplier_id, warehouse_id, purchase_id, purchase_ref, date, tax_rate, TaxNet, discount, shipping, notes, statut`) and `details[]` with the quantity originally purchased (to cap returnable quantity), current stock and serials.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@edit_purchase_return",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L957-L1126",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Purchase_Returns_edit",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "UserWarehouse",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant",
                    "PurchaseDetail"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase return id."
                    },
                    {
                        "name": "purchase_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Original purchase id (or `0`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchase_return` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchase_return": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/purchase/payment/{id}": {
            "get": {
                "operationId": "get_api_returns_purchase_payment_id",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "List refunds of a purchase return",
                "description": "Refund payments received against one purchase return (newest first) with payment method, plus the remaining `due`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@Payment_Returns",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L1130-L1162",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_returns_view",
                        "policy": "PaymentPurchaseReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "PaymentPurchaseReturns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Purchase return id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `due`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/purchase/{purchase}": {
            "delete": {
                "operationId": "delete_api_returns_purchase_purchase",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Delete a purchase return",
                "description": "Soft-deletes the return and its refunds (reverting account balances); stock, batches and serials are restored when the return was `completed`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@destroy",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L530-L664",
                "x-route-name": "purchase.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Purchase_Returns_delete",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "UserWarehouse",
                    "PurchaseReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "PaymentPurchaseReturns",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase return id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_returns_purchase_purchase",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Get a purchase return",
                "description": "Detail view: `purchase_return` header (`id, Ref, currency_*, purchase_id, purchase_ref, date, statut, note, discount, shipping, tax_rate, TaxNet, supplier_* fields, warehouse, GrandTotal, paid_amount, due, payment_status`), `details[]` and `company`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@show",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L1199-L1335",
                "x-route-name": "purchase.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Purchase_Returns_view",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase return id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`purchase_return`, `details[]`, `company`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchase_return": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "company": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_returns_purchase_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Update a purchase return",
                "description": "Reverses the stock/batch/serial effect of the old lines (when `completed`), then applies the new lines. Lines matched by detail `id`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@update",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L297-L526",
                "x-route-name": "purchase.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Purchase_Returns_edit",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "UserWarehouse",
                    "PurchaseReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase return id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`completed`/`pending`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_returns_purchase_purchase",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "Update a purchase return",
                "description": "Reverses the stock/batch/serial effect of the old lines (when `completed`), then applies the new lines. Lines matched by detail `id`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@update",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L297-L526",
                "x-route-name": "purchase.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Purchase_Returns_edit",
                        "policy": "PurchaseReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "PurchaseReturn",
                    "UserWarehouse",
                    "PurchaseReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase return id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`completed`/`pending`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/returns/purchase/{purchase}/edit": {
            "get": {
                "operationId": "get_api_returns_purchase_purchase_edit",
                "tags": [
                    "Purchase Returns"
                ],
                "summary": "(Not implemented) Edit-form data",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/returns/purchase/edit_purchase_return/{id}/{purchase_id}`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesReturnController@edit",
                "x-source": "app/Http/Controllers/PurchasesReturnController.php#L808-L813",
                "x-route-name": "purchase.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "purchase",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Purchase return id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale": {
            "get": {
                "operationId": "get_api_returns_sale",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "List sale returns",
                "description": "Paginated sale returns scoped to the caller's warehouses and record view. Rows: `id, date, Ref, statut, client_name, sale_ref, sale_id, warehouse_name, GrandTotal, paid_amount, due, payment_status, created_by`. Also returns `customers`, `warehouses`, `sales`, `accounts`, `payment_methods`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@index",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L36-L178",
                "x-route-name": "sale.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sale_Returns_view",
                        "policy": "SaleReturnPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "statut",
                    "client_id",
                    "payment_statut",
                    "warehouse_id",
                    "date",
                    "sale_id"
                ],
                "x-models": [
                    "UserWarehouse",
                    "SaleReturn",
                    "Client",
                    "Sale",
                    "Account",
                    "PaymentMethod",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Customer id."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact date."
                    },
                    {
                        "name": "payment_statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "`paid`, `partial`, `unpaid`."
                    },
                    {
                        "name": "sale_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Original sale id."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "`received` or `pending`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale_Return[]`, `totalRows`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sale_Return": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_returns_sale",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Create a sale return",
                "description": "Creates the return with its lines. When `statut` is `received`, each line's quantity (× unit operator × `pack_multiplier`) is added back to the warehouse stock, batch quantities are credited and serials listed in `imei_number` are marked returned. The return inherits the parent sale's currency snapshot.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@store",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L182-L319",
                "x-route-name": "sale.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sale_Returns_add",
                        "policy": "SaleReturnPolicy"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "Sale",
                    "Unit",
                    "SaleReturnDetails",
                    "product_warehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Lines: `{product_id, product_variant_id, quantity, sale_unit_id, Unit_price, tax_percent, tax_method, discount, discount_Method, subtotal, imei_number, pack_multiplier?, batches?}`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Original sale id (optional)."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`received` or `pending`. Required.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "statut",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "client_id": 3,
                                "warehouse_id": 1,
                                "sale_id": 41,
                                "date": "2026-09-07",
                                "statut": "received",
                                "tax_rate": 0,
                                "TaxNet": 0,
                                "discount": 0,
                                "shipping": 0,
                                "GrandTotal": 19.9,
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 1,
                                        "sale_unit_id": 1,
                                        "Unit_price": 19.9,
                                        "tax_percent": 0,
                                        "tax_method": "1",
                                        "discount": 0,
                                        "discount_Method": "2",
                                        "subtotal": 19.9,
                                        "imei_number": null
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale/create": {
            "get": {
                "operationId": "get_api_returns_sale_create",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "(Not implemented) Create-form lookups",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/returns/sale/create_sell_return/{id}` to pre-fill a return from a sale.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@create",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L1069-L1074",
                "x-route-name": "sale.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale/create_sell_return/{id}": {
            "get": {
                "operationId": "get_api_returns_sale_create_sell_return_id",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Pre-fill a return from a sale",
                "description": "Loads the sale's lines in *return form* shape: `sale_return` defaults (`client_id, warehouse_id, sale_id, sale_ref, statut received, zero tax/discount/shipping`) and `details[]` (`product_id, product_variant_id, code, name, quantity sold, sale_unit_id, Unit_price, tax fields, discount fields, subtotal, stock, imei_number, no_unit, del`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@create_sell_return",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L1150-L1277",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sale_Returns_add",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale_return` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale_return": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale/delete/by_selection": {
            "post": {
                "operationId": "post_api_returns_sale_delete_by_selection",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Delete several sale returns",
                "description": "Deletes each return in `selectedIds` with the same rules.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@delete_by_selection",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L718-L853",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Sale_Returns_delete",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "UserWarehouse",
                    "SaleReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "PaymentSaleReturns",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of sale return ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale/edit_sell_return/{id}/{sale_id}": {
            "get": {
                "operationId": "get_api_returns_sale_edit_sell_return_id_sale_id",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Get a sale return for editing",
                "description": "Form-shaped payload: `sale_return` header (`client_id, warehouse_id, sale_id, sale_ref, date, tax_rate, TaxNet, discount, shipping, notes, statut`) and `details[]` lines with the quantity originally sold (so the form can cap the returnable quantity), current stock and serial numbers.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@edit_sell_return",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L1409-L1564",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Sale_Returns_edit",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "UserWarehouse",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant",
                    "SaleDetail"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale return id."
                    },
                    {
                        "name": "sale_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Original sale id (use `0`/`null` for free-standing returns)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale_return` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale_return": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale/payment/{id}": {
            "get": {
                "operationId": "get_api_returns_sale_payment_id",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "List refunds of a sale return",
                "description": "Refund payments recorded against one sale return (newest first) with payment method, plus the remaining `due`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@Payment_Returns",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L857-L889",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "payment_returns_view",
                        "policy": "PaymentSaleReturnsPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "PaymentSaleReturns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale return id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `due`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale/pos_search_sales": {
            "get": {
                "operationId": "get_api_returns_sale_pos_search_sales",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Search sales for a POS return",
                "description": "Typeahead used by the POS return dialog: up to `limit` (max 50, default 10) recent sales matching `search` on Ref, exact GrandTotal or customer name. Each row: `id, Ref, date, client_id, client_name, warehouse_name, GrandTotal, sale_has_return`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@pos_search_sales",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L1089-L1148",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sale_Returns_add",
                        "policy": "SaleReturnPolicy"
                    }
                ],
                "x-models": [
                    "Sale",
                    "UserWarehouse",
                    "SaleReturn"
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Max rows (1–50)."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Ref, total or customer name."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sales[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns/sale/{sale}": {
            "delete": {
                "operationId": "delete_api_returns_sale_sale",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Delete a sale return",
                "description": "Soft-deletes the return and its refunds (reverting account balances); stock, batches and serials are reversed when the return was `received`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@destroy",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L574-L714",
                "x-route-name": "sale.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Sale_Returns_delete",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "UserWarehouse",
                    "SaleReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "PaymentSaleReturns",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale return id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_returns_sale_sale",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Get a sale return",
                "description": "Detail view: `sale_Return` header (`id, Ref, currency_*, sale_id, sale_ref, date, note, statut, discount, shipping, tax_rate, TaxNet, client_* fields, warehouse, GrandTotal, paid_amount, due, payment_status`), `details[]` lines and `company`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@show",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L925-L1065",
                "x-route-name": "sale.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sale_Returns_view",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale return id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale_Return`, `details[]`, `company`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale_Return": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "company": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_returns_sale_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Update a sale return",
                "description": "Reverses the stock/batch/serial effect of the old lines (when `received`), then applies the new lines. Lines matched by detail `id`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@update",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L323-L570",
                "x-route-name": "sale.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Sale_Returns_edit",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "UserWarehouse",
                    "SaleReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale return id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`received`/`pending`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_returns_sale_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sale Returns"
                ],
                "summary": "Update a sale return",
                "description": "Reverses the stock/batch/serial effect of the old lines (when `received`), then applies the new lines. Lines matched by detail `id`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@update",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L323-L570",
                "x-route-name": "sale.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Sale_Returns_edit",
                        "policy": "SaleReturnPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "UserWarehouse",
                    "SaleReturnDetails",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale return id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`received`/`pending`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/returns/sale/{sale}/edit": {
            "get": {
                "operationId": "get_api_returns_sale_sale_edit",
                "tags": [
                    "Sale Returns"
                ],
                "summary": "(Not implemented) Edit-form data",
                "description": "Empty stub; returns an empty `200`. Use `GET /api/returns/sale/edit_sell_return/{id}/{sale_id}`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesReturnController@edit",
                "x-source": "app/Http/Controllers/SalesReturnController.php#L1078-L1083",
                "x-route-name": "sale.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale return id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/returns_client": {
            "get": {
                "operationId": "get_api_returns_client",
                "tags": [
                    "Customers"
                ],
                "summary": "List a customer's sale returns (ledger)",
                "description": "Paginated sale returns for one customer, newest first. Rows: `id, Ref, date, statut, client_name, sale_ref, sale_id, warehouse_name, GrandTotal, paid_amount, due, payment_status`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@returnsByClient",
                "x-source": "app/Http/Controllers/ClientController.php#L1360-L1425",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SaleReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "x-exists": "clients,id",
                            "x-laravel-rules": [
                                "required",
                                "integer",
                                "exists:clients,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Customer id (query string, required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`returns[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "returns": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/roles": {
            "get": {
                "operationId": "get_api_roles",
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "List roles",
                "description": "Paginated roles with a `permissions_count` on each row. `search` matches name and description. `totalPermissions` is the number of distinct permission slugs known to the system.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@index",
                "x-source": "app/Http/Controllers/PermissionsController.php#L15-L50",
                "x-route-name": "roles.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "permissions_view",
                        "policy": "RolePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Role",
                    "Permission"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`roles[]`, `totalRows`, `totalPermissions`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "roles": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totalPermissions": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "roles": [
                                        {
                                            "id": 1,
                                            "name": "Owner",
                                            "label": "Owner",
                                            "description": "Full access",
                                            "status": 0,
                                            "permissions_count": 240
                                        }
                                    ],
                                    "totalRows": 1,
                                    "totalPermissions": 240
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_roles",
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "Create a role",
                "description": "Creates a role and attaches the given permission slugs. Unknown slugs are created on the fly in the `permissions` table, so the list is free-form — use the slugs shown on the endpoints in this documentation.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@store",
                "x-source": "app/Http/Controllers/PermissionsController.php#L54-L97",
                "x-route-name": "roles.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "permissions_add",
                        "policy": "RolePolicy"
                    }
                ],
                "x-models": [
                    "Role",
                    "Permission"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "permissions": {
                                        "x-inferred": true,
                                        "type": "array",
                                        "items": {},
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of permission slugs to grant."
                                    },
                                    "role": {
                                        "x-inferred": true,
                                        "type": "object",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Object with `name` (required) and `description`.",
                                        "properties": {
                                            "name": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Role name."
                                            }
                                        },
                                        "required": [
                                            "name"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "role": {
                                    "name": "Cashier",
                                    "description": "POS only"
                                },
                                "permissions": [
                                    "Pos_view",
                                    "Sales_view",
                                    "Sales_add",
                                    "Customers_view"
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/roles/delete/by_selection": {
            "post": {
                "operationId": "post_api_roles_delete_by_selection",
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "Delete several roles",
                "description": "Soft-deletes each role id in `selectedIds`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@delete_by_selection",
                "x-source": "app/Http/Controllers/PermissionsController.php#L164-L177",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "permissions_delete",
                        "policy": "RolePolicy"
                    }
                ],
                "x-models": [
                    "Role"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of role ids."
                                    }
                                }
                            },
                            "example": {
                                "selectedIds": [
                                    5,
                                    6
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/roles/{role}": {
            "delete": {
                "operationId": "delete_api_roles_role",
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "Delete a role",
                "description": "Soft-deletes the role. Users still assigned to it keep the `role_id` but lose their permissions, so reassign them first.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@destroy",
                "x-source": "app/Http/Controllers/PermissionsController.php#L151-L160",
                "x-route-name": "roles.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "permissions_delete",
                        "policy": "RolePolicy"
                    }
                ],
                "x-models": [
                    "Role"
                ],
                "parameters": [
                    {
                        "name": "role",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Role id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_roles_role",
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "(Not implemented) Get a role",
                "description": "Resource stub with an empty body; returns an empty `200`. Use `GET /api/roles/{role}/edit`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@show",
                "x-source": "app/Http/Controllers/PermissionsController.php#L101-L105",
                "x-route-name": "roles.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "role",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Role id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_roles_role",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "Update a role",
                "description": "Updates the role's attributes from the `role` object (`name`, `description`, `label`…) and **replaces** its permission set with `permissions`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@update",
                "x-source": "app/Http/Controllers/PermissionsController.php#L109-L147",
                "x-route-name": "roles.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "permissions_edit",
                        "policy": "RolePolicy"
                    }
                ],
                "x-models": [
                    "Role",
                    "Permission"
                ],
                "parameters": [
                    {
                        "name": "role",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Role fields as a nested object: `name` and `description`. Permissions are sent separately in `permissions`."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "permissions": {
                                        "x-inferred": true,
                                        "type": "array",
                                        "items": {},
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Complete array of permission slugs; previous ones are detached first."
                                    },
                                    "role": {
                                        "properties": {
                                            "name": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Role name (also used as the label)."
                                            }
                                        },
                                        "required": [
                                            "name"
                                        ],
                                        "description": "Role fields as a nested object: `name` and `description`. Permissions are sent separately in `permissions`.",
                                        "type": "object"
                                    }
                                }
                            },
                            "example": {
                                "role": {
                                    "name": "Cashier",
                                    "description": "POS + customers"
                                },
                                "permissions": [
                                    "Pos_view",
                                    "Sales_view",
                                    "Sales_add",
                                    "Customers_view",
                                    "Customers_add"
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_roles_role",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "Update a role",
                "description": "Updates the role's attributes from the `role` object (`name`, `description`, `label`…) and **replaces** its permission set with `permissions`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@update",
                "x-source": "app/Http/Controllers/PermissionsController.php#L109-L147",
                "x-route-name": "roles.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "permissions_edit",
                        "policy": "RolePolicy"
                    }
                ],
                "x-models": [
                    "Role",
                    "Permission"
                ],
                "parameters": [
                    {
                        "name": "role",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Role fields as a nested object: `name` and `description`. Permissions are sent separately in `permissions`."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "permissions": {
                                        "x-inferred": true,
                                        "type": "array",
                                        "items": {},
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Complete array of permission slugs; previous ones are detached first."
                                    },
                                    "role": {
                                        "properties": {
                                            "name": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Role name (also used as the label)."
                                            }
                                        },
                                        "required": [
                                            "name"
                                        ],
                                        "description": "Role fields as a nested object: `name` and `description`. Permissions are sent separately in `permissions`.",
                                        "type": "object"
                                    }
                                }
                            },
                            "example": {
                                "role": {
                                    "name": "Cashier",
                                    "description": "POS + customers"
                                },
                                "permissions": [
                                    "Pos_view",
                                    "Sales_view",
                                    "Sales_add",
                                    "Customers_view",
                                    "Customers_add"
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/roles/{role}/edit": {
            "get": {
                "operationId": "get_api_roles_role_edit",
                "tags": [
                    "Roles & Permissions"
                ],
                "summary": "Get a role with its permissions",
                "description": "Returns `role` (`name`, `description`) and `permissions` – the array of permission slugs assigned to it. Role `1` cannot be loaded and answers `401 {success:false}`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "PermissionsController@edit",
                "x-source": "app/Http/Controllers/PermissionsController.php#L190-L218",
                "x-route-name": "roles.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "permissions_edit",
                        "policy": "RolePolicy"
                    }
                ],
                "x-models": [
                    "Role"
                ],
                "parameters": [
                    {
                        "name": "role",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Role id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`role` and `permissions[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "permissions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "role": {}
                                    }
                                },
                                "example": {
                                    "permissions": [
                                        "Customers_view",
                                        "Customers_add",
                                        "Sales_view"
                                    ],
                                    "role": {
                                        "name": "Cashier",
                                        "description": "POS only"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sale_pdf/{id}": {
            "get": {
                "operationId": "get_api_sale_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Sale invoice PDF",
                "description": "A4 invoice for a sale: customer block, line items (with variant, batch and unit), totals, payments and the ZATCA QR when enabled. Layout follows the `sale` PDF template settings.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "SalesController@Sale_PDF",
                "x-source": "app/Http/Controllers/SalesController.php#L2618-L2757",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Sale",
                    "PaymentSale",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting",
                    "PosSetting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file `Sale_<Ref>.pdf`.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/sale_print_html/{id}": {
            "get": {
                "operationId": "get_api_sale_print_html_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Sale invoice HTML",
                "description": "Same template as the sale PDF returned as an HTML document for the browser print dialog (used by the POS A4 flow).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "SalesController@Sale_PDF_Inline",
                "x-source": "app/Http/Controllers/SalesController.php#L2766-L2917",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Sale",
                    "PaymentSale",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting",
                    "PosSetting"
                ],
                "x-response-type": "html",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "HTML document (printable view)",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/sales": {
            "get": {
                "operationId": "get_api_sales",
                "tags": [
                    "Sales"
                ],
                "summary": "List sales",
                "description": "Paginated sales scoped to the caller's warehouses and record view. Rows: `id, date, Ref, created_by, seller_name, statut, discount, shipping, GrandTotal, paid_amount, due, payment_status, shipping_status, warehouse_name, client_id, client_name, client_code, client_email, client_tele, client_adr, payment_methods (names used), currency_code, documents_count, sale_has_return, salereturn_id`. `search` matches Ref, statut, exact GrandTotal, payment/shipping status, customer and warehouse names. `stats` summarises the filtered set (totals, paid, due, counts by status). Also returns `stripe_key`, `customers`, `warehouses`, `accounts`, `payment_methods` for the page.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@index",
                "x-source": "app/Http/Controllers/SalesController.php#L57-L232",
                "x-route-name": "sales.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sales_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "statut",
                    "client_id",
                    "payment_statut",
                    "warehouse_id",
                    "date",
                    "shipping_status"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Sale",
                    "SaleReturn",
                    "Client",
                    "Account",
                    "PaymentMethod",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference (`LIKE`)."
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Customer id."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact sale date (`YYYY-MM-DD`)."
                    },
                    {
                        "name": "payment_statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "`paid`, `partial` or `unpaid`."
                    },
                    {
                        "name": "shipping_status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Shipment status (`ordered`, `packed`, `shipped`, `delivered`, `cancelled`)."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "`completed`, `pending` or `ordered`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sales[]`, `totalRows`, `stats`, lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stripe_key": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stats": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_sales",
                "tags": [
                    "Sales"
                ],
                "summary": "Create a sale",
                "description": "Creates a sale with its lines and, optionally, immediate payments.\n\n- When `statut` is `completed`, stock is deducted per line (quantity × unit operator × `pack_multiplier`), batch allocations and serials are consumed, and the customer earns loyalty points (`product.points × quantity`). Overselling is rejected unless allowed in settings.\n- `payments[]` records one payment row per entry and updates `paid_amount` / `payment_statut`; each account's balance is increased. Legacy single-payment fields (`amount`, `payment.payment_method_id`, `payment.account_id`, `change`) are still accepted.\n- `used_points` / `discount_from_points` redeem loyalty points (deducted from the customer).\n- `quotation_id` links the sale to the quotation it was converted from.\n- Multi-currency: send `currency_id` and `exchange_rate` to snapshot a document currency; amounts must be in the base currency.\n\nAfter commit the sale is pushed to QuickBooks when that integration is connected (`qbo_sync` in the response).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@store",
                "x-source": "app/Http/Controllers/SalesController.php#L279-L629",
                "x-route-name": "sales.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "Quotation",
                    "Product",
                    "Unit",
                    "SaleDetail",
                    "product_warehouse",
                    "PaymentSale",
                    "Account",
                    "Client"
                ],
                "x-notes": [
                    "Line structure: `product_id`, `product_variant_id`, `quantity`, `sale_unit_id`, `Unit_price`, `tax_percent`, `tax_method` (`1` exclusive / `2` inclusive), `discount`, `discount_Method` (`1` percent / `2` fixed), `subtotal`, `imei_number` (serials, comma-separated), `batches[]` (`{product_batch_id, qty}`), `product_pack_id` / `pack_name` / `pack_multiplier` (multi-pack), `price_type` (`retail`/`wholesale`)."
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total computed by the client."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Legacy single payment amount."
                                    },
                                    "change": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Cash change given back (legacy single payment).",
                                        "type": "number"
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale date (`YYYY-MM-DD`)."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Line items (see structure below).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount (percent or amount)."
                                    },
                                    "discount_Method": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1` percent, `2` fixed amount (default)."
                                    },
                                    "discount_from_points": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Discount amount granted for the redeemed points."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "payment": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Legacy single payment object `{payment_method_id, account_id}` used with `amount`.",
                                        "type": "object"
                                    },
                                    "payments": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Optional array of payments `[{amount, payment_method_id, account_id, change}]`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "quotation_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Source quotation id when converting."
                                    },
                                    "sales_agent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Commission sales agent id."
                                    },
                                    "seller_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Salesperson user id (when the salesperson switch is enabled)."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping cost.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`completed`, `pending` or `ordered`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "used_points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty points redeemed on this sale.",
                                        "type": "number"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    },
                                    "currency_id": {
                                        "type": "integer",
                                        "description": "Document currency id (multi-currency); omit for the base currency.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "exchange_rate": {
                                        "type": "number",
                                        "description": "Exchange rate snapshot for `currency_id`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "client_id": 3,
                                "warehouse_id": 1,
                                "date": "2026-09-06",
                                "statut": "completed",
                                "tax_rate": 0,
                                "TaxNet": 0,
                                "discount": 0,
                                "discount_Method": "2",
                                "shipping": 0,
                                "GrandTotal": 39.8,
                                "notes": "",
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 2,
                                        "sale_unit_id": 1,
                                        "Unit_price": 19.9,
                                        "tax_percent": 0,
                                        "tax_method": "1",
                                        "discount": 0,
                                        "discount_Method": "2",
                                        "subtotal": 39.8,
                                        "imei_number": null
                                    }
                                ],
                                "payments": [
                                    {
                                        "amount": 39.8,
                                        "payment_method_id": 1,
                                        "account_id": 1,
                                        "change": 0
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, new `sale_id`, QuickBooks sync result.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "sale_id": {},
                                        "quickbooks_invoice_id": {},
                                        "qbo_sync": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "sale_id": 41,
                                    "quickbooks_invoice_id": null,
                                    "qbo_sync": null
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales/create": {
            "get": {
                "operationId": "get_api_sales_create",
                "tags": [
                    "Sales"
                ],
                "summary": "Get lookups for the sale form",
                "description": "`clients`, the caller's `warehouses`, `sales_agents`, `accounts`, `payment_methods`, the Stripe public key, `point_to_amount_rate` (loyalty conversion), and salesperson-switch settings (`enable_pos_salesperson_switch`, `salespeople`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@create",
                "x-source": "app/Http/Controllers/SalesController.php#L2921-L2955",
                "x-route-name": "sales.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "Client",
                    "Account",
                    "PaymentMethod",
                    "SalesAgent",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "Form lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stripe_key": {},
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales_agents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "point_to_amount_rate": {},
                                        "enable_pos_salesperson_switch": {
                                            "type": "boolean"
                                        },
                                        "salespeople": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales/documents/{id}": {
            "delete": {
                "operationId": "delete_api_sales_documents_id",
                "tags": [
                    "Sales"
                ],
                "summary": "Delete a sale document",
                "description": "Soft-deletes the document row and removes the file from disk.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@deleteDocument",
                "x-source": "app/Http/Controllers/SalesController.php#L4254-L4285",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Sales_delete",
                        "policy": "SalePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`status: true`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Document deleted successfully"
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales/documents/{id}/download": {
            "get": {
                "operationId": "get_api_sales_documents_id_download",
                "tags": [
                    "Sales"
                ],
                "summary": "Download a sale document",
                "description": "Streams the stored file with its original name.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@downloadDocument",
                "x-source": "app/Http/Controllers/SalesController.php#L4224-L4251",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sales_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales/{id}/documents": {
            "get": {
                "operationId": "get_api_sales_id_documents",
                "tags": [
                    "Sales"
                ],
                "summary": "List documents attached to a sale",
                "description": "Files uploaded against the sale (`id, name, path, size, mime_type, created_at`), newest first.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@getDocuments",
                "x-source": "app/Http/Controllers/SalesController.php#L4151-L4167",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sales_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`documents[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_sales_id_documents",
                "tags": [
                    "Sales"
                ],
                "summary": "Upload documents to a sale",
                "description": "Uploads one or more files (max 10 MB each) as `documents[]` (multipart) into `/images/sale_documents/` and returns the new document ids.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@uploadDocuments",
                "x-source": "app/Http/Controllers/SalesController.php#L4170-L4221",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Sales_edit",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "documents": {
                                        "type": "array",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Array of files.",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "maxLength": 10240,
                                            "x-laravel-rules": [
                                                "required",
                                                "file",
                                                "max:10240"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`documents[]` (new ids).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Documents uploaded successfully"
                                        },
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales/{sale}": {
            "delete": {
                "operationId": "delete_api_sales_sale",
                "tags": [
                    "Sales"
                ],
                "summary": "Delete a sale",
                "description": "Soft-deletes the sale, its lines, payments (reverting account balances) and shipment. Stock is restored when the sale was `completed`; batch and serial ledgers are reversed. Sales that have a return cannot be deleted (`403`). The linked QuickBooks invoice is deleted when connected.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@destroy",
                "x-source": "app/Http/Controllers/SalesController.php#L1109-L1309",
                "x-route-name": "sales.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Sales_delete",
                        "policy": "SalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "UserWarehouse",
                    "SaleReturn",
                    "Unit",
                    "product_warehouse",
                    "Client",
                    "Shipment",
                    "PaymentSale",
                    "PaymentWithCreditCard",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `qbo_sync`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "qbo_sync": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Return exists or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_sales_sale",
                "tags": [
                    "Sales"
                ],
                "summary": "Get a sale",
                "description": "Detail view. `sale` carries the header (`id, Ref, date, note, statut, warehouse, currency_*, discount, discount_Method, shipping, tax_rate, TaxNet, client_* fields, GrandTotal, paid_amount, due, payment_status, discount_from_points, previous_dues, sale_has_return, salereturn_id, seller_name, sales_agent, documents…`), `details[]` the lines (`code, name, quantity, unit, price, discount, tax, total, imei_number, batches[], serials[], pack info`) and `company` the company block for printing. Amounts are in the document currency.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@show",
                "x-source": "app/Http/Controllers/SalesController.php#L1489-L1645",
                "x-route-name": "sales.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sales_view",
                        "policy": "SalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "SaleReturn",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale`, `details[]`, `company`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "company": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_sales_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sales"
                ],
                "summary": "Update a sale",
                "description": "Same payload as create (without `payments`). The old lines' stock effect is reversed and the new one applied when the sale is `completed`; lines are matched by detail `id`. A sale that has a return cannot be edited (`403`). Loyalty points are re-balanced. Re-synced to QuickBooks when connected.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@update",
                "x-source": "app/Http/Controllers/SalesController.php#L654-L1105",
                "x-route-name": "sales.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Sales_edit",
                        "policy": "SalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "UserWarehouse",
                    "SaleReturn",
                    "SaleDetail",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing lines).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "discount_Method": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1` percent / `2` fixed."
                                    },
                                    "discount_from_points": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Points discount amount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "sales_agent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sales agent id."
                                    },
                                    "seller_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Salesperson user id."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping cost.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`completed`, `pending`, `ordered`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "used_points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty points redeemed.",
                                        "type": "number"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `sale_id`, `qbo_sync`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "sale_id": {},
                                        "qbo_sync": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Return exists or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_sales_sale",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sales"
                ],
                "summary": "Update a sale",
                "description": "Same payload as create (without `payments`). The old lines' stock effect is reversed and the new one applied when the sale is `completed`; lines are matched by detail `id`. A sale that has a return cannot be edited (`403`). Loyalty points are re-balanced. Re-synced to QuickBooks when connected.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@update",
                "x-source": "app/Http/Controllers/SalesController.php#L654-L1105",
                "x-route-name": "sales.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Sales_edit",
                        "policy": "SalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Sale",
                    "UserWarehouse",
                    "SaleReturn",
                    "SaleDetail",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Grand total."
                                    },
                                    "TaxNet": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax amount."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale date."
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing lines).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "discount_Method": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1` percent / `2` fixed."
                                    },
                                    "discount_from_points": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Points discount amount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "sales_agent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sales agent id."
                                    },
                                    "seller_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Salesperson user id."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping cost.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`completed`, `pending`, `ordered`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "used_points": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty points redeemed.",
                                        "type": "number"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `sale_id`, `qbo_sync`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "sale_id": {},
                                        "qbo_sync": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Return exists or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/sales/{sale}/edit": {
            "get": {
                "operationId": "get_api_sales_sale_edit",
                "tags": [
                    "Sales"
                ],
                "summary": "Get a sale for editing",
                "description": "Form-shaped payload: `sale` (`client_id, warehouse_id, date, statut, tax_rate, TaxNet, discount, discount_Method, shipping, notes, sales_agent_id, seller_id, used_points…`), `details[]` (each line with `id, detail_id, product_id, product_variant_id, code, name, quantity, sale_unit_id, Unit_price, Net_price, tax_percent, tax_method, discount, discount_Method, subtotal, stock, current, imei_number, batches, pack fields`), lookups and loyalty data. A sale that already has a return cannot be edited (`403`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@edit",
                "x-source": "app/Http/Controllers/SalesController.php#L2959-L3218",
                "x-route-name": "sales.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Sales_edit",
                        "policy": "SalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "Sale",
                    "UserWarehouse",
                    "Client",
                    "Warehouse",
                    "Setting",
                    "ProductPack",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant",
                    "SalesAgent"
                ],
                "parameters": [
                    {
                        "name": "sale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sale`, `details[]`, `clients[]`, `warehouses[]`, `sales_agents[]`, `discount_from_points`, `point_to_amount_rate`, salesperson settings.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale": {},
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sales_agents": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "discount_from_points": {},
                                        "point_to_amount_rate": {},
                                        "enable_pos_salesperson_switch": {
                                            "type": "boolean"
                                        },
                                        "salespeople": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Sale has a return, or warehouse restriction.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_3d_dashboard_data": {
            "get": {
                "operationId": "get_api_sales_3d_dashboard_data",
                "tags": [
                    "Dashboard"
                ],
                "summary": "Get 3D sales dashboard data",
                "description": "Series for the 3D charts page: sales by month × warehouse, top products by month, a product price/qty scatter, payment-method split, hour × day-of-week heatmap, top clients and headline KPIs.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "Sales3DDashboardController@data",
                "x-source": "app/Http/Controllers/Sales3DDashboardController.php#L21-L71",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Start date."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "End date."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Restrict to one warehouse (`0` = all assigned)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sales_by_month_warehouse, top_products_by_month, product_scatter, payment_methods, hour_dow_heatmap, top_clients, kpis}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sales_by_month_warehouse": {},
                                        "top_products_by_month": {},
                                        "product_scatter": {},
                                        "payment_methods": {},
                                        "hour_dow_heatmap": {},
                                        "top_clients": {},
                                        "kpis": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_agents": {
            "get": {
                "operationId": "get_api_sales_agents",
                "tags": [
                    "Sales Agents"
                ],
                "summary": "List sales agents",
                "description": "Paginated agents with linked user and `sale_commissions_count`. `search` matches name, email, code or phone.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\SalesAgentController@index",
                "x-source": "app/Http/Controllers/Commission/SalesAgentController.php#L12-L47",
                "x-route-name": "sales_agents.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SalesAgent"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "is_active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Active flag."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `data.agents[]` and `data.totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_sales_agents",
                "tags": [
                    "Sales Agents"
                ],
                "summary": "Create a sales agent",
                "description": "Creates a sales agent (external commission-earning seller): name, contact details, linked user/employee and commission program.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\SalesAgentController@store",
                "x-source": "app/Http/Controllers/Commission/SalesAgentController.php#L49-L73",
                "x-route-name": "sales_agents.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "commissions_add",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SalesAgent"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Short code."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active (default true)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "user_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "users,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:users,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked user account."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the agent.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {}
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_agents/{sales_agent}": {
            "delete": {
                "operationId": "delete_api_sales_agents_sales_agent",
                "tags": [
                    "Sales Agents"
                ],
                "summary": "Delete a sales agent",
                "description": "Soft-deletes a sales agent; sales keep their agent reference.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\SalesAgentController@destroy",
                "x-source": "app/Http/Controllers/Commission/SalesAgentController.php#L109-L115",
                "x-route-name": "sales_agents.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "commissions_delete",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SalesAgent"
                ],
                "parameters": [
                    {
                        "name": "sales_agent",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Agent id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope, `data` null.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "nullable": true,
                                            "type": "string"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_sales_agents_sales_agent",
                "tags": [
                    "Sales Agents"
                ],
                "summary": "Get a sales agent",
                "description": "One sales agent with program, sales count and commission totals.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\SalesAgentController@show",
                "x-source": "app/Http/Controllers/Commission/SalesAgentController.php#L75-L80",
                "x-route-name": "sales_agents.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "commissions_view",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SalesAgent"
                ],
                "parameters": [
                    {
                        "name": "sales_agent",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Agent id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with the agent.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {}
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_sales_agents_sales_agent",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sales Agents"
                ],
                "summary": "Update a sales agent",
                "description": "Updates a sales agent with the same fields as creation.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\SalesAgentController@update",
                "x-source": "app/Http/Controllers/Commission/SalesAgentController.php#L82-L107",
                "x-route-name": "sales_agents.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SalesAgent"
                ],
                "parameters": [
                    {
                        "name": "sales_agent",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Agent id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "user_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "users,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:users,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "User."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the agent.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_sales_agents_sales_agent",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sales Agents"
                ],
                "summary": "Update a sales agent",
                "description": "Updates a sales agent with the same fields as creation.",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\SalesAgentController@update",
                "x-source": "app/Http/Controllers/Commission/SalesAgentController.php#L82-L107",
                "x-route-name": "sales_agents.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "commissions_edit",
                        "policy": "CommissionProgramPolicy"
                    }
                ],
                "x-models": [
                    "SalesAgent"
                ],
                "parameters": [
                    {
                        "name": "sales_agent",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Agent id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "user_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "users,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:users,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "User."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Envelope with the agent.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/sales_agents_list_for_select": {
            "get": {
                "operationId": "get_api_sales_agents_list_for_select",
                "tags": [
                    "Sales Agents"
                ],
                "summary": "Active agents for dropdowns",
                "description": "List agents for dropdowns (id, name, code).",
                "x-section": "Commissions",
                "x-surface": "admin",
                "x-controller": "Commission\\SalesAgentController@listForSelect",
                "x-source": "app/Http/Controllers/Commission/SalesAgentController.php#L118-L124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SalesAgent"
                ],
                "responses": {
                    "200": {
                        "description": "Envelope with `[{id, name, code}]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_client": {
            "get": {
                "operationId": "get_api_sales_client",
                "tags": [
                    "Customers"
                ],
                "summary": "List a customer's sales (ledger)",
                "description": "Paginated sales for one customer, newest first, for the customer ledger. `search` matches `Ref`, `statut`, `payment_statut`, warehouse name and customer name. Each row: `id, date, Ref, warehouse_name, client_name, statut, GrandTotal, paid_amount, due, payment_status, shipping_status`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ClientController@salesByClient",
                "x-source": "app/Http/Controllers/ClientController.php#L927-L998",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Customers_view",
                        "policy": "ClientPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "x-exists": "clients,id",
                            "x-laravel-rules": [
                                "required",
                                "integer",
                                "exists:clients,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Customer id (query string, required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sales[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "totalRows": 2,
                                    "sales": [
                                        {
                                            "id": 41,
                                            "date": "2026-09-01",
                                            "Ref": "SL_1120",
                                            "warehouse_name": "Main",
                                            "client_name": "ACME Ltd",
                                            "statut": "completed",
                                            "GrandTotal": 540.5,
                                            "paid_amount": 0,
                                            "due": 540.5,
                                            "payment_status": "unpaid"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_delete_by_selection": {
            "post": {
                "operationId": "post_api_sales_delete_by_selection",
                "tags": [
                    "Sales"
                ],
                "summary": "Delete several sales",
                "description": "Deletes each sale in `selectedIds` with the same rules as the single delete. Stops with `403` at the first sale that has a return.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@delete_by_selection",
                "x-source": "app/Http/Controllers/SalesController.php#L1313-L1485",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Sales_delete",
                        "policy": "SalePolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "SaleReturn",
                    "Sale",
                    "UserWarehouse",
                    "SaleDetail",
                    "Shipment",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "Client",
                    "PaymentSale",
                    "Account"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of sale ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "Return exist for the Transaction": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this sale (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_print_invoice/{id}": {
            "get": {
                "operationId": "get_api_sales_print_invoice_id",
                "tags": [
                    "Sales"
                ],
                "summary": "Get POS receipt data",
                "description": "**Public** (no authentication). Returns everything needed to render a POS receipt for a sale: `sale` header (Ref, date, discounts incl. `discount_from_points`, `promotions[]`, shipping, tax, client/warehouse/seller names, GrandTotal, paid, previous dues, notes), `details[]` lines (name, code, quantity, unit, price, total, batch/serial info), `payments[]`, `setting` (company block), `pos_settings` (receipt layout options), `symbol`, ZATCA QR / status when e-invoicing is enabled and `public_invoice_url`. Amounts are in the document currency.",
                "x-section": "Sales",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "SalesController@Print_Invoice_POS",
                "x-source": "app/Http/Controllers/SalesController.php#L1649-L1826",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Sale",
                    "PromotionUsage",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "PaymentSale",
                    "Setting",
                    "PosSetting",
                    "ZatcaDocument"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Receipt payload.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "name": {},
                                        "code": {},
                                        "amount": {
                                            "type": "number"
                                        },
                                        "symbol": {},
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "setting": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "pos_settings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale": {},
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "zatca_qr": {},
                                        "zatca_status": {},
                                        "public_invoice_url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/sales_send_email": {
            "post": {
                "operationId": "post_api_sales_send_email",
                "tags": [
                    "Sales"
                ],
                "summary": "Email the invoice to the customer",
                "description": "Sends the *sale* email template (System Settings → Notifications) to the customer's email with the placeholders `{contact_name}`, `{business_name}`, `{invoice_url}` (public PDF link), `{invoice_number}`, `{total_amount}`, `{paid_amount}`, `{due_amount}` filled in.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@Send_Email",
                "x-source": "app/Http/Controllers/SalesController.php#L3569-L3628",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sales_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Sale",
                    "Setting",
                    "EmailMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale id."
                                    }
                                }
                            },
                            "example": {
                                "id": 41
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message: \"Email sent successfully\"`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Email sent successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_send_sms": {
            "post": {
                "operationId": "post_api_sales_send_sms",
                "tags": [
                    "Sales"
                ],
                "summary": "SMS the invoice to the customer",
                "description": "Sends the *sale* SMS template to the customer's phone through the default SMS gateway (Twilio, Termii, Nexmo/Vonage, Infobip…) with the same placeholders as the email.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@Send_SMS",
                "x-source": "app/Http/Controllers/SalesController.php#L3632-L3773",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Sales_view",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Sale",
                    "Setting",
                    "sms_gateway",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "500": {
                        "description": "Gateway error message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sales_send_whatsapp": {
            "post": {
                "operationId": "post_api_sales_send_whatsapp",
                "tags": [
                    "Sales"
                ],
                "summary": "Build a WhatsApp message for the invoice",
                "description": "Returns the *sale* SMS template rendered for this sale plus the customer's `phone`, so the client can open a `wa.me` link. Nothing is sent server-side.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@sales_send_whatsapp",
                "x-source": "app/Http/Controllers/SalesController.php#L3776-L3829",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Sale",
                    "Setting",
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`message` and `phone`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {},
                                        "phone": {}
                                    }
                                },
                                "example": {
                                    "message": "Dear ACME Ltd, invoice SL_1120 …",
                                    "phone": "+212600000000"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Customer has no phone number.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Phone number is missing"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/disconnect": {
            "post": {
                "operationId": "post_api_salla_disconnect",
                "tags": [
                    "Salla"
                ],
                "summary": "Disconnect the Salla store",
                "description": "Drop the token pair and store metadata; app credentials stay.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@disconnect",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L81-L100",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "x-models": [
                    "SallaSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/logs": {
            "delete": {
                "operationId": "delete_api_salla_logs",
                "tags": [
                    "Salla"
                ],
                "summary": "Clear Salla logs",
                "description": "Clears the Salla sync log.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@clearLogs",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L206-L213",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "x-models": [
                    "SallaLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_salla_logs",
                "tags": [
                    "Salla"
                ],
                "summary": "Salla logs",
                "description": "Paginated Salla sync log entries.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@logs",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L194-L204",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SallaLog"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Level."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/reset-mappings": {
            "post": {
                "operationId": "post_api_salla_reset_mappings",
                "tags": [
                    "Salla"
                ],
                "summary": "Reset Salla mappings",
                "description": "Deletes all product/category mappings between Stocky and Salla so the next sync re-matches items by SKU.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@resetMappings",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L130-L143",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entity_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "product",
                                            "variant",
                                            "customer",
                                            "order"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:product,variant,customer,order"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`product` (also clears variants), `variant`, `customer`, `order`; omit for all."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `deleted`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "deleted": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/settings": {
            "get": {
                "operationId": "get_api_salla_settings",
                "tags": [
                    "Salla"
                ],
                "summary": "Get Salla settings",
                "description": "Current Salla settings (client ID, token status, default warehouse/customer, sync options); secrets are masked.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@settings",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L20-L45",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "x-models": [
                    "SallaSetting",
                    "Warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `connected`, `client_id`, secret flags, `store {id, name, domain}`, `warehouse_id`, `warehouses[]`, token expiry, `last_sync_at`, `connect_url`, `callback_url`, `webhook_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "connected": {},
                                        "client_id": {},
                                        "has_client_secret": {},
                                        "has_webhook_secret": {},
                                        "store": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "name": {},
                                                "domain": {}
                                            }
                                        },
                                        "warehouse_id": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "access_token_expires_at": {
                                            "type": "string"
                                        },
                                        "last_sync_at": {
                                            "type": "string"
                                        },
                                        "connect_url": {
                                            "type": "string"
                                        },
                                        "callback_url": {
                                            "type": "string"
                                        },
                                        "webhook_url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_salla_settings",
                "tags": [
                    "Salla"
                ],
                "summary": "Save Salla settings",
                "description": "Saves the Salla OAuth client credentials, default warehouse/customer and which entities to sync.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@saveSettings",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L47-L78",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "x-models": [
                    "SallaSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Salla app client id."
                                    },
                                    "client_secret": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Client secret (write-only)."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse for stock and orders."
                                    },
                                    "webhook_secret": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Webhook signing secret (write-only)."
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/stats": {
            "get": {
                "operationId": "get_api_salla_stats",
                "tags": [
                    "Salla"
                ],
                "summary": "Sync statistics",
                "description": "Counters: mapped products, orders imported, webhook events, last sync.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@stats",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L123-L128",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Mapped counts.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/sync/inventory": {
            "post": {
                "operationId": "post_api_salla_sync_inventory",
                "tags": [
                    "Salla"
                ],
                "summary": "Push stock levels",
                "description": "Pushes current stock quantities of mapped products to Salla.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@syncInventory",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L164-L176",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call (default 30).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `pushed`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/sync/orders": {
            "post": {
                "operationId": "post_api_salla_sync_orders",
                "tags": [
                    "Salla"
                ],
                "summary": "Pull orders into sales",
                "description": "Imports new Salla orders as sales; already imported orders are skipped.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@syncOrders",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L178-L192",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "page_info": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Page number.",
                                        "type": "integer"
                                    },
                                    "per_page": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Page size (default 15).",
                                        "type": "integer"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse for the sales."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `imported`, `skipped`, `next_page`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/sync/products": {
            "post": {
                "operationId": "post_api_salla_sync_products",
                "tags": [
                    "Salla"
                ],
                "summary": "Push or pull products",
                "description": "Synchronises products in the configured direction (`direction`: `push` Stocky → Salla or `pull` Salla → Stocky), matching by SKU.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@syncProducts",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L145-L162",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push: rows per call (default 15).",
                                        "type": "integer"
                                    },
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`push` (default) or `pull`."
                                    },
                                    "only_unsynced": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push: skip already-mapped products.",
                                        "type": "boolean"
                                    },
                                    "page_info": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pull: page number.",
                                        "type": "integer"
                                    },
                                    "per_page": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pull: page size (default 30).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push: resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Result with counts.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/test-connection": {
            "post": {
                "operationId": "post_api_salla_test_connection",
                "tags": [
                    "Salla"
                ],
                "summary": "Test the Salla connection",
                "description": "Calls the Salla merchant API with the stored token and reports success or the error.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SallaSyncController@testConnection",
                "x-source": "app/Http/Controllers/Integrations/SallaSyncController.php#L102-L121",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SallaSettingPolicy"
                    }
                ],
                "x-models": [
                    "SallaSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not connected / failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Not connected"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/salla/webhook": {
            "post": {
                "operationId": "post_api_salla_webhook",
                "tags": [
                    "Salla"
                ],
                "summary": "Salla webhook receiver",
                "description": "Public. Verified with the `X-Salla-Signature` header against the webhook secret.",
                "x-section": "Integrations",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Integrations\\SallaWebhookController@handle",
                "x-source": "app/Http/Controllers/Integrations/SallaWebhookController.php#L18-L55",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "SallaSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid payload.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Invalid payload"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid signature.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Invalid signature"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/school/attendance/register": {
            "get": {
                "operationId": "get_api_school_attendance_register",
                "tags": [
                    "School: Attendance"
                ],
                "summary": "Class register for a date",
                "description": "Every active student of the class with the mark already recorded (if any).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAttendanceController@register",
                "x-source": "app/Http/Controllers/SchoolAttendanceController.php#L28-L79",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "StudentAttendancePolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "StudentEnrollment",
                    "StudentAttendance"
                ],
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-exists": "school_classes,id",
                            "x-laravel-rules": [
                                "required",
                                "exists:school_classes,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date",
                            "nullable": true,
                            "x-laravel-rules": [
                                "nullable",
                                "date"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Date (default today)."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "nullable": true,
                            "x-exists": "class_sections,id",
                            "x-laravel-rules": [
                                "nullable",
                                "exists:class_sections,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Section."
                    },
                    {
                        "name": "subject_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "nullable": true,
                            "x-exists": "subjects,id",
                            "x-laravel-rules": [
                                "nullable",
                                "exists:subjects,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Subject (for per-period registers)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`date`, `already_marked`, `students[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "date": {
                                            "type": "string"
                                        },
                                        "already_marked": {
                                            "type": "boolean"
                                        },
                                        "students": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "student_id": {},
                                        "enrollment_id": {},
                                        "name": {},
                                        "admission_number": {},
                                        "roll_number": {},
                                        "image_url": {
                                            "type": "string"
                                        },
                                        "status": {},
                                        "remarks": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_attendance_register",
                "tags": [
                    "School: Attendance"
                ],
                "summary": "Save a register",
                "description": "Upserts every entry in one transaction. Future dates are refused.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAttendanceController@save",
                "x-source": "app/Http/Controllers/SchoolAttendanceController.php#L82-L126",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "StudentAttendancePolicy"
                    }
                ],
                "x-models": [
                    "StudentAttendance"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "entries": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "x-inferred": true,
                                                    "type": "string",
                                                    "enum": [
                                                        "present",
                                                        "absent",
                                                        "late",
                                                        "excused",
                                                        "half_day"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "in:present,absent,late,excused,half_day"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Mark."
                                                },
                                                "student_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Student."
                                                }
                                            },
                                            "required": [
                                                "status",
                                                "student_id"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Marks."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Section."
                                    },
                                    "subject_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "subjects,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:subjects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject."
                                    },
                                    "entries.*.remarks": {
                                        "type": "string",
                                        "description": "Remarks.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "date",
                                    "entries"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `saved`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "saved": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/attendance/summary": {
            "get": {
                "operationId": "get_api_school_attendance_summary",
                "tags": [
                    "School: Attendance"
                ],
                "summary": "Attendance summary by day",
                "description": "Day-by-day summary for a class over a range, for the monthly sheet.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAttendanceController@summary",
                "x-source": "app/Http/Controllers/SchoolAttendanceController.php#L129-L167",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "StudentAttendancePolicy"
                    }
                ],
                "x-models": [
                    "StudentAttendance"
                ],
                "parameters": [
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "nullable": true,
                            "x-exists": "school_classes,id",
                            "x-laravel-rules": [
                                "nullable",
                                "exists:school_classes,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date",
                            "nullable": true,
                            "x-laravel-rules": [
                                "nullable",
                                "date"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "To (default today)."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Section."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date",
                            "nullable": true,
                            "x-laravel-rules": [
                                "nullable",
                                "date"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "From (default month start)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`days[] {date, present, absent, late, excused, half_day, rate}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "days": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/classes": {
            "get": {
                "operationId": "get_api_school_classes",
                "tags": [
                    "School: Academics"
                ],
                "summary": "List classes",
                "description": "With section, subject and active-student counts for the year.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@classes",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L105-L141",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "SchoolClass",
                    "ClassSection",
                    "Subject",
                    "AcademicYear",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year for the student count (default current)."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`classes[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "classes": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_classes",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Create a class",
                "description": "Creates a class/grade (name, code, level, description).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@storeClass",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L143-L151",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "SchoolClass"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "level": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Numeric level for ordering."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. `Grade 5`)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "level": {},
                                        "description": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/classes/{id}": {
            "delete": {
                "operationId": "delete_api_school_classes_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Delete a class",
                "description": "Soft-deletes a class. Classes with enrolled students cannot be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@destroyClass",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L163-L181",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "SchoolClass",
                    "StudentEnrollment",
                    "ClassSection",
                    "Subject"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Class id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Has enrolments.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This class has {$enrolled} enrolment(s). Move those students first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_classes_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Update a class",
                "description": "Updates a class with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@updateClass",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L153-L161",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "SchoolClass"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Class id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "level": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Numeric level for ordering."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. `Grade 5`)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "level": {},
                                        "description": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/dashboard": {
            "get": {
                "operationId": "get_api_school_dashboard",
                "tags": [
                    "School: Dashboard"
                ],
                "summary": "School dashboard",
                "description": "School KPIs: students by status and class, teachers, today's attendance rate, fee collection (invoiced vs paid), upcoming exams.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolDashboardController@dashboard",
                "x-source": "app/Http/Controllers/SchoolDashboardController.php#L31-L96",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "dashboard",
                        "slug": "school_dashboard",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "StudentEnrollment",
                    "Student",
                    "StudentAttendance",
                    "Teacher",
                    "SchoolClass",
                    "ClassSection",
                    "Subject",
                    "SchoolInvoice",
                    "SchoolPayment"
                ],
                "responses": {
                    "200": {
                        "description": "Current year, student / teacher / class counts, today's attendance, fee figures, attendance trend, by-class breakdown, upcoming exams, today's periods.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_year": {
                                            "type": "object"
                                        },
                                        "students_total": {
                                            "type": "integer"
                                        },
                                        "students_enrolled": {
                                            "type": "integer"
                                        },
                                        "students_male": {
                                            "type": "integer"
                                        },
                                        "students_female": {
                                            "type": "integer"
                                        },
                                        "teachers_total": {
                                            "type": "integer"
                                        },
                                        "classes_total": {
                                            "type": "integer"
                                        },
                                        "sections_total": {
                                            "type": "integer"
                                        },
                                        "subjects_total": {
                                            "type": "integer"
                                        },
                                        "attendance_marked_today": {},
                                        "present_today": {},
                                        "absent_today": {
                                            "type": "integer"
                                        },
                                        "attendance_rate_today": {
                                            "type": "number"
                                        },
                                        "fees_billed": {
                                            "type": "number"
                                        },
                                        "fees_collected": {
                                            "type": "number"
                                        },
                                        "fees_outstanding": {
                                            "type": "number"
                                        },
                                        "fees_overdue_count": {
                                            "type": "integer"
                                        },
                                        "collected_month": {
                                            "type": "number"
                                        },
                                        "attendance_trend": {},
                                        "by_class": {},
                                        "upcoming_exams": {},
                                        "today_periods": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/enrollments": {
            "get": {
                "operationId": "get_api_school_enrollments",
                "tags": [
                    "School: Students"
                ],
                "summary": "List enrolments",
                "description": "Paginated enrolments (student × academic year × class/section) with roll number and status. Filter by `academic_year_id`, `class_id`, `section_id`, `status`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@enrollments",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L302-L347",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "StudentEnrollmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Section."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Enrolment status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`enrollments[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "enrollments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_enrollments",
                "tags": [
                    "School: Students"
                ],
                "summary": "Enrol a student",
                "description": "Creates or updates the student's enrolment for the year.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@storeEnrollment",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L349-L364",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "StudentEnrollmentPolicy"
                    }
                ],
                "x-models": [
                    "Student"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "enrolled_on": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "enrollment_status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "roll_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Roll number."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Section."
                                    },
                                    "student_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "students,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:students,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Student."
                                    }
                                },
                                "required": [
                                    "academic_year_id",
                                    "class_id",
                                    "student_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/enrollments/promote": {
            "post": {
                "operationId": "post_api_school_enrollments_promote",
                "tags": [
                    "School: Students"
                ],
                "summary": "Promote a class to the next year",
                "description": "Marks source enrolments `promoted` (or `repeated` for `repeat_ids`) and creates new ones in the target year / class. Students already enrolled in the target year are skipped, so the call is idempotent.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@promote",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L405-L467",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "StudentEnrollmentPolicy"
                    }
                ],
                "x-models": [
                    "StudentEnrollment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source class."
                                    },
                                    "from_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source year."
                                    },
                                    "repeat_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Students who repeat the class.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "student_ids": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Restrict to these students (default whole class).",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "to_class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target class."
                                    },
                                    "to_section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target section."
                                    },
                                    "to_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-rules": [
                                            "different:from_year_id"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id",
                                            "different:from_year_id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target year."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "from_year_id",
                                    "to_class_id",
                                    "to_year_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `promoted`, `repeated`, `skipped`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "promoted": {},
                                        "repeated": {},
                                        "skipped": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/enrollments/{id}": {
            "delete": {
                "operationId": "delete_api_school_enrollments_id",
                "tags": [
                    "School: Students"
                ],
                "summary": "Delete an enrolment",
                "description": "Deletes an enrolment record.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@destroyEnrollment",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L388-L395",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "StudentEnrollmentPolicy"
                    }
                ],
                "x-models": [
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Enrolment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_enrollments_id",
                "tags": [
                    "School: Students"
                ],
                "summary": "Update an enrolment",
                "description": "Moves a student to another class/section, changes the roll number or status (`active`, `promoted`, `transferred`, `left`).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@updateEnrollment",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L366-L386",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "StudentEnrollmentPolicy"
                    }
                ],
                "x-models": [
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Enrolment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "roll_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Roll number."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Section."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "promoted",
                                            "transferred",
                                            "left",
                                            "repeated"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,promoted,transferred,left,repeated"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams": {
            "get": {
                "operationId": "get_api_school_exams",
                "tags": [
                    "School: Exams"
                ],
                "summary": "List exams",
                "description": "Paginated exams with academic year, term, dates and status. Filter by `academic_year_id`, `term`, `status`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@index",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L33-L75",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Exam",
                    "ExamSubject"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "term",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Term."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`exams[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "exams": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_exams",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Create an exam",
                "description": "Creates an exam (name, academic year, term, start/end dates). Papers are added afterwards.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@store",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L77-L85",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "scheduled",
                                            "ongoing",
                                            "completed",
                                            "published"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:draft,scheduled,ongoing,completed,published"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "term": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "term_1",
                                            "term_2",
                                            "term_3",
                                            "final",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:term_1,term_2,term_3,final,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Term."
                                    }
                                },
                                "required": [
                                    "academic_year_id",
                                    "name",
                                    "status",
                                    "term"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_year_id": {},
                                        "name": {},
                                        "term": {},
                                        "start_date": {},
                                        "end_date": {},
                                        "status": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams/{examId}/papers": {
            "get": {
                "operationId": "get_api_school_exams_examId_papers",
                "tags": [
                    "School: Exams"
                ],
                "summary": "List papers of an exam",
                "description": "Papers of an exam: class, subject, date, time, room, max and pass marks.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@papers",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L125-L165",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam",
                    "ExamSubject",
                    "ExamResult"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`exam` and `papers[]` (with marks-entered counts).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "exam": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "name": {},
                                                "term": {},
                                                "status": {},
                                                "academic_year_id": {},
                                                "year_name": {}
                                            }
                                        },
                                        "papers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_exams_examId_papers",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Add a paper",
                "description": "Adds a paper (class + subject) to the exam with its schedule and marks.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@storePaper",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L167-L184",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam",
                    "ExamSubject"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "duration_minutes": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 600,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:5",
                                            "max:600"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Duration."
                                    },
                                    "exam_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "max_marks": {
                                        "type": "number",
                                        "minimum": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Maximum marks."
                                    },
                                    "pass_marks": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-rules": [
                                            "lte:max_marks"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0",
                                            "lte:max_marks"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Pass marks."
                                    },
                                    "room": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Room."
                                    },
                                    "start_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start `HH:MM`."
                                    },
                                    "subject_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "subjects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:subjects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "max_marks",
                                    "pass_marks",
                                    "subject_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "class_id": {},
                                        "subject_id": {},
                                        "exam_date": {},
                                        "start_time": {},
                                        "duration_minutes": {},
                                        "max_marks": {},
                                        "pass_marks": {},
                                        "room": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams/{examId}/papers/generate": {
            "post": {
                "operationId": "post_api_school_exams_examId_papers_generate",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Generate papers for a class",
                "description": "One paper per active subject of the class.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@generatePapers",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L215-L254",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam",
                    "Subject",
                    "ExamSubject"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "max_marks": {
                                        "type": "number",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Max marks (default 100)."
                                    },
                                    "pass_marks": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Pass marks (default subject pass mark)."
                                    }
                                },
                                "required": [
                                    "class_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams/{examId}/papers/{paperId}": {
            "delete": {
                "operationId": "delete_api_school_exams_examId_papers_paperId",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Delete a paper",
                "description": "Deletes a paper and the marks entered for it.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@destroyPaper",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L200-L212",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "ExamSubject",
                    "ExamResult"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    },
                    {
                        "name": "paperId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Paper id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_exams_examId_papers_paperId",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Update a paper",
                "description": "Grades are recomputed when max marks change.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@updatePaper",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L186-L198",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "ExamSubject"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    },
                    {
                        "name": "paperId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Paper id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "duration_minutes": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 600,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:5",
                                            "max:600"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Duration."
                                    },
                                    "exam_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "max_marks": {
                                        "type": "number",
                                        "minimum": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Maximum marks."
                                    },
                                    "pass_marks": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-rules": [
                                            "lte:max_marks"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0",
                                            "lte:max_marks"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Pass marks."
                                    },
                                    "room": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Room."
                                    },
                                    "start_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start `HH:MM`."
                                    },
                                    "subject_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "subjects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:subjects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "max_marks",
                                    "pass_marks",
                                    "subject_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "class_id": {},
                                        "subject_id": {},
                                        "exam_date": {},
                                        "start_time": {},
                                        "duration_minutes": {},
                                        "max_marks": {},
                                        "pass_marks": {},
                                        "room": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams/{examId}/papers/{paperId}/results": {
            "post": {
                "operationId": "post_api_school_exams_examId_papers_paperId_results",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Save marks",
                "description": "Null marks = absent. Grades are derived from the percentage.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@saveResults",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L311-L348",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "ExamSubject",
                    "ExamResult"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    },
                    {
                        "name": "paperId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Paper id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "results": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "marks": {
                                                    "x-rules": [
                                                        "dynamic:'nullable|numeric|min:0|max:' . $max"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "dynamic:'nullable|numeric|min:0|max:' . $max"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Marks (0..max) or null.",
                                                    "type": "number"
                                                },
                                                "student_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Student."
                                                }
                                            },
                                            "required": [
                                                "student_id"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Rows."
                                    },
                                    "results.*.remarks": {
                                        "type": "string",
                                        "description": "Remarks.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "results"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `saved`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "saved": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams/{examId}/papers/{paperId}/sheet": {
            "get": {
                "operationId": "get_api_school_exams_examId_papers_paperId_sheet",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Mark sheet of a paper",
                "description": "The mark sheet for one paper: every enrolled student, with any mark.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@sheet",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L261-L308",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam",
                    "ExamSubject",
                    "StudentEnrollment",
                    "ExamResult"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    },
                    {
                        "name": "paperId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Paper id."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Section."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`paper` and `students[] {student_id, name, roll_number, marks, is_absent, grade, remarks}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "paper": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "exam_name": {},
                                                "subject_name": {},
                                                "class_name": {},
                                                "max_marks": {
                                                    "type": "number"
                                                },
                                                "pass_marks": {
                                                    "type": "number"
                                                },
                                                "exam_date": {
                                                    "type": "string"
                                                }
                                            }
                                        },
                                        "students": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "student_id": {},
                                        "name": {},
                                        "admission_number": {},
                                        "roll_number": {},
                                        "section_name": {},
                                        "marks": {
                                            "type": "number"
                                        },
                                        "is_absent": {
                                            "type": "boolean"
                                        },
                                        "grade": {},
                                        "remarks": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams/{examId}/report-card": {
            "get": {
                "operationId": "get_api_school_exams_examId_report_card",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Class report card",
                "description": "Every student × every paper with totals, percentage, grade, position and pass/fail, plus class average and pass rate.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@reportCard",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L354-L452",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam",
                    "ExamSubject",
                    "StudentEnrollment",
                    "ExamResult"
                ],
                "parameters": [
                    {
                        "name": "examId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-exists": "school_classes,id",
                            "x-laravel-rules": [
                                "required",
                                "exists:school_classes,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Section."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`exam`, `papers[]`, `rows[]`, `class_average`, `pass_rate`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "student_id": {},
                                        "name": {},
                                        "admission_number": {},
                                        "roll_number": {},
                                        "section_name": {},
                                        "subjects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "obtained": {
                                            "type": "number"
                                        },
                                        "total": {
                                            "type": "number"
                                        },
                                        "percentage": {},
                                        "grade": {},
                                        "failed_subjects": {},
                                        "result": {
                                            "type": "string"
                                        },
                                        "exam": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "name": {},
                                                "term": {}
                                            }
                                        },
                                        "papers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "rows": {},
                                        "class_average": {
                                            "type": "number"
                                        },
                                        "pass_rate": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/exams/{id}": {
            "delete": {
                "operationId": "delete_api_school_exams_id",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Delete an exam",
                "description": "Deletes an exam with its papers and marks.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@destroy",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L97-L119",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam",
                    "ExamResult",
                    "ExamSubject"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Marks already recorded.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This exam already has {$entered} mark(s) recorded. Delete those first if you really mean to remove it."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_exams_id",
                "tags": [
                    "School: Exams"
                ],
                "summary": "Update an exam",
                "description": "Updates an exam with the same fields as creation; `status` moves it through `scheduled`, `ongoing`, `completed`, `published`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolExamController@update",
                "x-source": "app/Http/Controllers/SchoolExamController.php#L87-L95",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ExamPolicy"
                    }
                ],
                "x-models": [
                    "Exam"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Exam id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "scheduled",
                                            "ongoing",
                                            "completed",
                                            "published"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:draft,scheduled,ongoing,completed,published"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "term": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "term_1",
                                            "term_2",
                                            "term_3",
                                            "final",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:term_1,term_2,term_3,final,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Term."
                                    }
                                },
                                "required": [
                                    "academic_year_id",
                                    "name",
                                    "status",
                                    "term"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_year_id": {},
                                        "name": {},
                                        "term": {},
                                        "start_date": {},
                                        "end_date": {},
                                        "status": {},
                                        "notes": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-invoices": {
            "get": {
                "operationId": "get_api_school_fee_invoices",
                "tags": [
                    "School: Fees"
                ],
                "summary": "List fee invoices",
                "description": "Paginated fee invoices with student, class, amount, paid, due and status. Filter by `student_id`, `class_id`, `status`, `academic_year_id`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@invoices",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L100-L147",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SchoolInvoice"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "outstanding",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = unpaid / partial."
                    },
                    {
                        "name": "overdue",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = past due date."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    },
                    {
                        "name": "student_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Student."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`invoices[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "invoices": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_fee_invoices",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Create a fee invoice",
                "description": "Generates a `FEE-…` reference.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@storeInvoice",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L176-L205",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "SchoolInvoice",
                    "AcademicYear"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year (default current)."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "discount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "invoice_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {},
                                        "description": "`[{fee_structure_id?, description, quantity, unit_price}]`.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "unpaid",
                                            "partial",
                                            "paid",
                                            "cancelled"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:draft,unpaid,partial,paid,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status (default `unpaid`)."
                                    },
                                    "student_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "students,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:students,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Student."
                                    }
                                },
                                "required": [
                                    "items",
                                    "student_id",
                                    "items"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-invoices/generate": {
            "post": {
                "operationId": "post_api_school_fee_invoices_generate",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Generate invoices for a class",
                "description": "One invoice per active student of the class with the selected fee structures; students already invoiced for the same lines in the year are skipped.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@generateInvoices",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L259-L341",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "FeeStructure",
                    "StudentEnrollment",
                    "SchoolInvoice",
                    "SchoolInvoiceItem"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "fee_structure_ids": {
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Fee structures to bill.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "invoice_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Section."
                                    }
                                },
                                "required": [
                                    "academic_year_id",
                                    "class_id",
                                    "fee_structure_ids"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `created`, `skipped`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "created": {},
                                        "skipped": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-invoices/{id}": {
            "delete": {
                "operationId": "delete_api_school_fee_invoices_id",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Delete a fee invoice",
                "description": "Deletes an unpaid fee invoice.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@destroyInvoice",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L232-L250",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "SchoolInvoice",
                    "SchoolInvoiceItem"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Has payments.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This invoice has payments against it. Reverse those first, or cancel the invoice instead."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_school_fee_invoices_id",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Get a fee invoice",
                "description": "One fee invoice with its lines (fee structures), payments and balance.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@showInvoice",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L149-L174",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "SchoolInvoice"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`invoice` with `items[]` and `payments[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "invoice": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_fee_invoices_id",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Update a fee invoice",
                "description": "Updates a fee invoice with the same fields as creation; totals are recomputed.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@updateInvoice",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L207-L230",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "SchoolInvoice"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Year (default current)."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "discount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Discount."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "invoice_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {},
                                        "description": "Lines (full replacement).",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "draft",
                                            "unpaid",
                                            "partial",
                                            "paid",
                                            "cancelled"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:draft,unpaid,partial,paid,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status (default `unpaid`)."
                                    },
                                    "student_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "students,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:students,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Student."
                                    }
                                },
                                "required": [
                                    "items",
                                    "student_id",
                                    "items"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-invoices/{id}/payments": {
            "post": {
                "operationId": "post_api_school_fee_invoices_id_payments",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Record a fee payment",
                "description": "Records a payment on the invoice (`amount`, `date`, `payment_method_id`, `reference`, `notes`) and updates the balance and status.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@storePayment",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L347-L387",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "SchoolInvoice",
                    "SchoolPayment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount."
                                    },
                                    "method": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Method."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "paid_on": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date."
                                    }
                                },
                                "required": [
                                    "amount"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and remaining `due`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "due": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-invoices/{invoiceId}/payments/{paymentId}": {
            "delete": {
                "operationId": "delete_api_school_fee_invoices_invoiceId_payments_paymentId",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Delete a fee payment",
                "description": "Deletes a fee payment and recomputes the invoice balance.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@destroyPayment",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L389-L402",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "SchoolInvoice",
                    "SchoolPayment"
                ],
                "parameters": [
                    {
                        "name": "invoiceId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Invoice id."
                    },
                    {
                        "name": "paymentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Payment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-payments": {
            "get": {
                "operationId": "get_api_school_fee_payments",
                "tags": [
                    "School: Fees"
                ],
                "summary": "List fee payments",
                "description": "Paginated fee payments with invoice, student, amount, method and date. Filter by date range and method.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@payments",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L404-L451",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SchoolPayment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "method",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Method."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "student_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Student."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]`, `totalRows`, `collected`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "collected": {},
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-structures": {
            "get": {
                "operationId": "get_api_school_fee_structures",
                "tags": [
                    "School: Fees"
                ],
                "summary": "List fee structures",
                "description": "Fee structures (tuition, transport, …) per class and academic year with amount, frequency and optional flag.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@structures",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L35-L65",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "FeeStructure"
                ],
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year (default current)."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`fee_structures[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "fee_structures": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_fee_structures",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Create a fee structure",
                "description": "Creates a fee structure: name, class, academic year, amount, frequency (one-time, monthly, term, yearly), due date and optional flag.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@storeStructure",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L67-L75",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "FeeStructure"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class (optional = all classes)."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default due date."
                                    },
                                    "frequency": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "once",
                                            "monthly",
                                            "termly",
                                            "yearly"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:once,monthly,termly,yearly"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`once`, `monthly`, `termly`, `yearly`."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "is_optional": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Optional fee."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. *Tuition*)."
                                    }
                                },
                                "required": [
                                    "academic_year_id",
                                    "amount",
                                    "frequency",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_year_id": {},
                                        "class_id": {},
                                        "name": {},
                                        "frequency": {},
                                        "amount": {},
                                        "due_date": {},
                                        "is_optional": {},
                                        "is_active": {},
                                        "description": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/fee-structures/{id}": {
            "delete": {
                "operationId": "delete_api_school_fee_structures_id",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Delete a fee structure",
                "description": "Deletes a fee structure not used by any invoice.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@destroyStructure",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L87-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "FeeStructure"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Structure id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_fee_structures_id",
                "tags": [
                    "School: Fees"
                ],
                "summary": "Update a fee structure",
                "description": "Updates a fee structure with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolFeeController@updateStructure",
                "x-source": "app/Http/Controllers/SchoolFeeController.php#L77-L85",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SchoolInvoicePolicy"
                    }
                ],
                "x-models": [
                    "FeeStructure"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Structure id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "academic_years,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:academic_years,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class (optional = all classes)."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "due_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default due date."
                                    },
                                    "frequency": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "once",
                                            "monthly",
                                            "termly",
                                            "yearly"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:once,monthly,termly,yearly"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`once`, `monthly`, `termly`, `yearly`."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "is_optional": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Optional fee."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. *Tuition*)."
                                    }
                                },
                                "required": [
                                    "academic_year_id",
                                    "amount",
                                    "frequency",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_year_id": {},
                                        "class_id": {},
                                        "name": {},
                                        "frequency": {},
                                        "amount": {},
                                        "due_date": {},
                                        "is_optional": {},
                                        "is_active": {},
                                        "description": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/meta": {
            "get": {
                "operationId": "get_api_school_meta",
                "tags": [
                    "School: Dashboard"
                ],
                "summary": "School form lookups",
                "description": "Every select the school forms need, in one call. Students are NOT included — a school can hold thousands, so those forms search instead. /",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolDashboardController@meta",
                "x-source": "app/Http/Controllers/SchoolDashboardController.php#L187-L216",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "school_students_view",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "SchoolClass",
                    "ClassSection",
                    "Subject",
                    "Teacher",
                    "FeeStructure"
                ],
                "responses": {
                    "200": {
                        "description": "`academic_years[]`, `current_year_id`, `classes[]`, `sections[]`, `subjects[]`, `teachers[]`, `fee_structures[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_years": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "current_year_id": {},
                                        "classes": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sections": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "subjects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "teachers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "fee_structures": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/reports/absentees": {
            "get": {
                "operationId": "get_api_school_reports_absentees",
                "tags": [
                    "School: Reports"
                ],
                "summary": "Low-attendance students",
                "description": "Students whose attendance has fallen below a threshold — the list a head of year actually acts on. Defaults to 75%. /",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolReportController@absentees",
                "x-source": "app/Http/Controllers/SchoolReportController.php#L124-L190",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "school_reports",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AcademicYear",
                    "StudentAttendance",
                    "Student",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "threshold",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "number"
                        },
                        "description": "Attendance % threshold (default 75)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/reports/attendance": {
            "get": {
                "operationId": "get_api_school_reports_attendance",
                "tags": [
                    "School: Reports"
                ],
                "summary": "Attendance rate per class",
                "description": "Attendance rate per class over a date range.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolReportController@attendance",
                "x-source": "app/Http/Controllers/SchoolReportController.php#L80-L118",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "school_reports",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "StudentAttendance",
                    "SchoolClass"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]`, `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/reports/defaulters": {
            "get": {
                "operationId": "get_api_school_reports_defaulters",
                "tags": [
                    "School: Reports"
                ],
                "summary": "Fee defaulters",
                "description": "Families who owe money, worst first — the bursar's chase list.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolReportController@defaulters",
                "x-source": "app/Http/Controllers/SchoolReportController.php#L285-L353",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "school_reports",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AcademicYear",
                    "SchoolInvoice",
                    "Student",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (student, guardian, invoices, due, days overdue), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "id": {},
                                        "student_name": {},
                                        "admission_number": {},
                                        "class_name": {},
                                        "section_name": {},
                                        "guardian_name": {},
                                        "guardian_phone": {},
                                        "invoices": {
                                            "type": "integer"
                                        },
                                        "due": {
                                            "type": "number"
                                        },
                                        "earliest_due": {
                                            "type": "string"
                                        },
                                        "days_overdue": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/reports/enrollment": {
            "get": {
                "operationId": "get_api_school_reports_enrollment",
                "tags": [
                    "School: Reports"
                ],
                "summary": "Enrolment report",
                "description": "Enrolment by class: headcount, gender split, capacity.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolReportController@enrollment",
                "x-source": "app/Http/Controllers/SchoolReportController.php#L34-L77",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "school_reports",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AcademicYear",
                    "StudentEnrollment",
                    "ClassSection",
                    "SchoolClass"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (students, gender split, capacity, utilisation), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "class_name": {},
                                        "level": {
                                            "type": "integer"
                                        },
                                        "sections": {
                                            "type": "integer"
                                        },
                                        "students": {
                                            "type": "integer"
                                        },
                                        "male": {
                                            "type": "integer"
                                        },
                                        "female": {
                                            "type": "integer"
                                        },
                                        "capacity": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "utilisation": {
                                            "type": "number"
                                        },
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/reports/fees": {
            "get": {
                "operationId": "get_api_school_reports_fees",
                "tags": [
                    "School: Reports"
                ],
                "summary": "Fee collection per class",
                "description": "Fee collection per class: billed, collected, outstanding.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolReportController@fees",
                "x-source": "app/Http/Controllers/SchoolReportController.php#L244-L282",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "school_reports",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AcademicYear",
                    "SchoolInvoice",
                    "SchoolClass"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (invoices, billed, collected, outstanding), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/reports/performance": {
            "get": {
                "operationId": "get_api_school_reports_performance",
                "tags": [
                    "School: Reports"
                ],
                "summary": "Exam performance per class / subject",
                "description": "Exam performance per class: average, pass rate, best and worst.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolReportController@performance",
                "x-source": "app/Http/Controllers/SchoolReportController.php#L193-L241",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "school_reports",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Exam",
                    "ExamSubject",
                    "ExamResult"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "exam_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Exam (default latest)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (average, highest, lowest, pass rate), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "id": {},
                                        "class_name": {},
                                        "subject_name": {},
                                        "max_marks": {},
                                        "entered": {
                                            "type": "integer"
                                        },
                                        "absent": {
                                            "type": "integer"
                                        },
                                        "average": {},
                                        "average_pct": {
                                            "type": "number"
                                        },
                                        "highest": {
                                            "type": "number"
                                        },
                                        "lowest": {
                                            "type": "number"
                                        },
                                        "passed": {
                                            "type": "integer"
                                        },
                                        "pass_rate": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/reports/teachers": {
            "get": {
                "operationId": "get_api_school_reports_teachers",
                "tags": [
                    "School: Reports"
                ],
                "summary": "Teacher workload",
                "description": "Teacher workload: periods a week, subjects and form classes.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolReportController@teachers",
                "x-source": "app/Http/Controllers/SchoolReportController.php#L356-L394",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report",
                        "slug": "school_reports",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AcademicYear",
                    "TimetableSlot",
                    "ClassSection",
                    "Teacher"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rows[]` (weekly periods, subjects, classes, form classes, busiest day), `totalRows`, `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "teacher_name": {},
                                        "specialization": {},
                                        "is_active": {
                                            "type": "boolean"
                                        },
                                        "weekly_periods": {
                                            "type": "integer"
                                        },
                                        "subjects": {
                                            "type": "integer"
                                        },
                                        "classes": {
                                            "type": "integer"
                                        },
                                        "form_classes": {
                                            "type": "integer"
                                        },
                                        "busiest_day": {
                                            "type": "object"
                                        },
                                        "rows": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "totals": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/search/students": {
            "get": {
                "operationId": "get_api_school_search_students",
                "tags": [
                    "School: Dashboard"
                ],
                "summary": "Student type-ahead",
                "description": "Type-ahead over students for every form that needs one. Capped at 20 — a picker is for finding a known student, not browsing the roll. /",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolDashboardController@searchStudents",
                "x-source": "app/Http/Controllers/SchoolDashboardController.php#L222-L261",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "school_students_view",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "Student",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year for the class label."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name, admission number or guardian phone."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`students[] {id, name, admission_number, class_id, class_name, guardian_phone, label}` (max 20).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "students": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "id": {},
                                        "name": {},
                                        "admission_number": {},
                                        "class_id": {},
                                        "class_name": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "guardian_phone": {},
                                        "label": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/sections": {
            "get": {
                "operationId": "get_api_school_sections",
                "tags": [
                    "School: Academics"
                ],
                "summary": "List sections",
                "description": "Sections (divisions) of classes with form teacher, room and capacity. Filter by `class_id`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@sections",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L187-L225",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "ClassSection",
                    "AcademicYear",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year for the student count."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`sections[] {…, students, is_full}` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "sections": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "id": {},
                                        "class_id": {},
                                        "class_name": {},
                                        "name": {},
                                        "capacity": {},
                                        "room": {},
                                        "teacher_id": {},
                                        "teacher_name": {},
                                        "is_active": {
                                            "type": "boolean"
                                        },
                                        "students": {},
                                        "is_full": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_sections",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Create a section",
                "description": "Creates a section under a class (name, form teacher, room, capacity).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@storeSection",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L227-L242",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "ClassSection"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "capacity": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Seats."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. `A`)."
                                    },
                                    "room": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Room."
                                    },
                                    "teacher_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "teachers,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:teachers,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Form teacher."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "class_id": {},
                                        "name": {},
                                        "capacity": {},
                                        "room": {},
                                        "teacher_id": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/sections/{id}": {
            "delete": {
                "operationId": "delete_api_school_sections_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Delete a section",
                "description": "Soft-deletes a section. Sections with enrolled students cannot be deleted.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@destroySection",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L263-L279",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "ClassSection",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Section id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Holds students.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This section holds {$enrolled} student(s). Move them first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_sections_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Update a section",
                "description": "Updates a section with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@updateSection",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L244-L261",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "ClassSection"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Section id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "capacity": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Seats."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. `A`)."
                                    },
                                    "room": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Room."
                                    },
                                    "teacher_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "teachers,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:teachers,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Form teacher."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "class_id": {},
                                        "name": {},
                                        "capacity": {},
                                        "room": {},
                                        "teacher_id": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/students": {
            "get": {
                "operationId": "get_api_school_students",
                "tags": [
                    "School: Students"
                ],
                "summary": "List students",
                "description": "Sortable `id, admission_number, name, gender, date_of_birth, admission_date, status, created_at`; `search` matches name, admission number, guardian name/phone.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@index",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L34-L97",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "school_students_view",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "AcademicYear",
                    "Student",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year (default current)."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Enrolled class (in the year)."
                    },
                    {
                        "name": "gender",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Gender."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Section."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Student status."
                    },
                    {
                        "name": "unassigned",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = no enrolment in the year."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`students[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "students": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_students",
                "tags": [
                    "School: Students"
                ],
                "summary": "Register a student",
                "description": "Multipart. `admission_number` is generated when omitted. Sending `class_id` also creates the enrolment.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@store",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L99-L124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "school_students_add",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "Student"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enrolment year (default current)."
                                    },
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "admission_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admission date."
                                    },
                                    "admission_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'nullable|string|max:32|unique:students,admission_number' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'nullable|string|max:32|unique:students,admission_number' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admission number (unique)."
                                    },
                                    "blood_group": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Blood group."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Enrol into this class."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked customer for fee billing."
                                    },
                                    "date_of_birth": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "before_or_equal:today"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "before_or_equal:today"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date of birth."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "enrolled_on": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enrolment date.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "enrollment_status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enrolment status (default `active`)."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "male",
                                            "female",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:male,female,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`male`, `female`, `other`."
                                    },
                                    "guardian_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Guardian email."
                                    },
                                    "guardian_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guardian."
                                    },
                                    "guardian_occupation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Occupation."
                                    },
                                    "guardian_phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guardian phone."
                                    },
                                    "guardian_relation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Relation."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "medical_notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Medical notes."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Full name."
                                    },
                                    "national_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "National id.",
                                        "type": "string"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "roll_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Roll number."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Section."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "inactive",
                                            "graduated",
                                            "transferred",
                                            "expelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,inactive,graduated,transferred,expelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Student status."
                                    }
                                },
                                "required": [
                                    "gender",
                                    "name",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success`, `id`, `admission_number`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "gender": {},
                                        "date_of_birth": {},
                                        "admission_date": {},
                                        "blood_group": {},
                                        "phone": {},
                                        "email": {},
                                        "address": {},
                                        "city": {},
                                        "national_id": {},
                                        "medical_notes": {},
                                        "guardian_name": {},
                                        "guardian_relation": {},
                                        "guardian_phone": {},
                                        "guardian_email": {},
                                        "guardian_occupation": {},
                                        "client_id": {},
                                        "notes": {},
                                        "status": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {},
                                        "admission_number": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/students/delete/by_selection": {
            "post": {
                "operationId": "post_api_school_students_delete_by_selection",
                "tags": [
                    "School: Students"
                ],
                "summary": "Delete selected students",
                "description": "Bulk soft-delete of students by `selectedIds`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@deleteBySelection",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L221-L229",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "school_students_delete",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "Student"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Student ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/students/{id}": {
            "delete": {
                "operationId": "delete_api_school_students_id",
                "tags": [
                    "School: Students"
                ],
                "summary": "Delete a student",
                "description": "Soft-deletes a student; enrolments, attendance and fee records are kept.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@destroy",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L212-L219",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "school_students_delete",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "Student"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Student id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_school_students_id",
                "tags": [
                    "School: Students"
                ],
                "summary": "Get a student",
                "description": "One student with guardian details, current enrolment, attendance summary and fee balance.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@show",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L126-L163",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "school_students_view",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "Student",
                    "AcademicYear",
                    "SchoolInvoice",
                    "StudentAttendance",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Student id."
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year for the enrolment shown."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`student` (with enrolment, attendance rate, fees due).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "student": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/students/{id}/edit": {
            "get": {
                "operationId": "get_api_school_students_id_edit",
                "tags": [
                    "School: Students"
                ],
                "summary": "Edit-form data for a student",
                "description": "The student with the lookups (classes, sections, years) needed by the edit form.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@edit",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L165-L180",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "school_students_edit",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "Student"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Student id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`student` with `image_url`, `class_id`, `section_id`, `roll_number`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "student": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/students/{id}/timeline": {
            "get": {
                "operationId": "get_api_school_students_id_timeline",
                "tags": [
                    "School: Students"
                ],
                "summary": "Student timeline",
                "description": "Everything filed under one student, for the detail page's tabs.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@timeline",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L232-L296",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "school_students_view",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "Student",
                    "AcademicYear",
                    "ExamResult",
                    "StudentEnrollment",
                    "StudentAttendance",
                    "SchoolInvoice"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Student id."
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`enrollments[]`, `attendance[]`, `attendance_summary`, `results[]`, `invoices[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "exam_name": {},
                                        "subject_name": {},
                                        "exam_date": {
                                            "type": "string"
                                        },
                                        "marks": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "max_marks": {},
                                        "percentage": {
                                            "type": "number"
                                        },
                                        "grade": {},
                                        "is_absent": {
                                            "type": "boolean"
                                        },
                                        "passed": {},
                                        "enrollments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "attendance": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "attendance_summary": {},
                                        "results": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "invoices": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/students/{id}/update": {
            "post": {
                "operationId": "post_api_school_students_id_update",
                "tags": [
                    "School: Students"
                ],
                "summary": "Update a student",
                "description": "Multipart POST; same fields as create plus `remove_image`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolStudentController@update",
                "x-source": "app/Http/Controllers/SchoolStudentController.php#L182-L210",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "school_students_edit",
                        "policy": "StudentPolicy"
                    }
                ],
                "x-models": [
                    "Student"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Student id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enrolment year (default current)."
                                    },
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "admission_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admission date."
                                    },
                                    "admission_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'nullable|string|max:32|unique:students,admission_number' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'nullable|string|max:32|unique:students,admission_number' . ($ignoreId ? ',' . $ignoreId : '')"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admission number (unique)."
                                    },
                                    "blood_group": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Blood group."
                                    },
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Enrol into this class."
                                    },
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked customer for fee billing."
                                    },
                                    "date_of_birth": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "before_or_equal:today"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "before_or_equal:today"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Date of birth."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "enrolled_on": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enrolment date.",
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "enrollment_status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enrolment status (default `active`)."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "male",
                                            "female",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:male,female,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`male`, `female`, `other`."
                                    },
                                    "guardian_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Guardian email."
                                    },
                                    "guardian_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guardian."
                                    },
                                    "guardian_occupation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Occupation."
                                    },
                                    "guardian_phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Guardian phone."
                                    },
                                    "guardian_relation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Relation."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "medical_notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Medical notes."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Full name."
                                    },
                                    "national_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "National id.",
                                        "type": "string"
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "remove_image": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remove photo.",
                                        "type": "boolean"
                                    },
                                    "roll_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Roll number."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Section."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "inactive",
                                            "graduated",
                                            "transferred",
                                            "expelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,inactive,graduated,transferred,expelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Student status."
                                    }
                                },
                                "required": [
                                    "gender",
                                    "name",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "gender": {},
                                        "date_of_birth": {},
                                        "admission_date": {},
                                        "blood_group": {},
                                        "phone": {},
                                        "email": {},
                                        "address": {},
                                        "city": {},
                                        "national_id": {},
                                        "medical_notes": {},
                                        "guardian_name": {},
                                        "guardian_relation": {},
                                        "guardian_phone": {},
                                        "guardian_email": {},
                                        "guardian_occupation": {},
                                        "client_id": {},
                                        "notes": {},
                                        "status": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/subjects": {
            "get": {
                "operationId": "get_api_school_subjects",
                "tags": [
                    "School: Academics"
                ],
                "summary": "List subjects",
                "description": "Subjects with class, code, type (core/elective), credit and pass mark. Filter by `class_id`.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@subjects",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L285-L314",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "Subject"
                ],
                "parameters": [
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name or code."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Subject type."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`subjects[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "subjects": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_subjects",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Create a subject",
                "description": "Creates a subject for a class.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@storeSubject",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L316-L324",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "Subject"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class (optional = generic)."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "credit": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Credits."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "pass_mark": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Pass mark %."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "core",
                                            "elective",
                                            "optional"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:core,elective,optional"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`core`, `elective`, `optional`."
                                    }
                                },
                                "required": [
                                    "name",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "class_id": {},
                                        "type": {},
                                        "credit": {},
                                        "pass_mark": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/subjects/{id}": {
            "delete": {
                "operationId": "delete_api_school_subjects_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Delete a subject",
                "description": "Soft-deletes a subject; timetable slots and papers using it are kept.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@destroySubject",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L336-L343",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "Subject"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Subject id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_subjects_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Update a subject",
                "description": "Updates a subject with the same fields as creation.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@updateSubject",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L326-L334",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "Subject"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Subject id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class (optional = generic)."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 32,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:32"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Code."
                                    },
                                    "credit": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Credits."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "pass_mark": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Pass mark %."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "core",
                                            "elective",
                                            "optional"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:core,elective,optional"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`core`, `elective`, `optional`."
                                    }
                                },
                                "required": [
                                    "name",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "code": {},
                                        "class_id": {},
                                        "type": {},
                                        "credit": {},
                                        "pass_mark": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/teachers": {
            "get": {
                "operationId": "get_api_school_teachers",
                "tags": [
                    "School: Teachers"
                ],
                "summary": "List teachers",
                "description": "With weekly period and form-class counts.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTeacherController@index",
                "x-source": "app/Http/Controllers/SchoolTeacherController.php#L22-L74",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "TeacherPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Teacher",
                    "ClassSection",
                    "TimetableSlot"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` / `0`."
                    },
                    {
                        "name": "gender",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Gender."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`teachers[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "teachers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_teachers",
                "tags": [
                    "School: Teachers"
                ],
                "summary": "Create a teacher",
                "description": "Multipart.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTeacherController@store",
                "x-source": "app/Http/Controllers/SchoolTeacherController.php#L76-L87",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "TeacherPolicy"
                    }
                ],
                "x-models": [
                    "Teacher"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "employee_code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Staff code."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked HR employee."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "male",
                                            "female",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:male,female,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Gender."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "joining_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Joining date."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "qualification": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Qualification."
                                    },
                                    "salary": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Salary."
                                    },
                                    "specialization": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Specialisation."
                                    }
                                },
                                "required": [
                                    "gender",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "employee_code": {},
                                        "employee_id": {},
                                        "gender": {},
                                        "phone": {},
                                        "email": {},
                                        "qualification": {},
                                        "specialization": {},
                                        "joining_date": {},
                                        "salary": {},
                                        "address": {},
                                        "notes": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/teachers/delete/by_selection": {
            "post": {
                "operationId": "post_api_school_teachers_delete_by_selection",
                "tags": [
                    "School: Teachers"
                ],
                "summary": "Delete selected teachers",
                "description": "Bulk soft-delete of teachers by `selectedIds`; their sections and timetable slots are detached.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTeacherController@deleteBySelection",
                "x-source": "app/Http/Controllers/SchoolTeacherController.php#L126-L136",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "TeacherPolicy"
                    }
                ],
                "x-models": [
                    "ClassSection",
                    "TimetableSlot",
                    "Teacher"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Teacher ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/teachers/{id}": {
            "delete": {
                "operationId": "delete_api_school_teachers_id",
                "tags": [
                    "School: Teachers"
                ],
                "summary": "Delete a teacher",
                "description": "Sections and timetable slots are detached.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTeacherController@destroy",
                "x-source": "app/Http/Controllers/SchoolTeacherController.php#L111-L124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "TeacherPolicy"
                    }
                ],
                "x-models": [
                    "Teacher",
                    "ClassSection",
                    "TimetableSlot"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Teacher id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/teachers/{id}/timetable": {
            "get": {
                "operationId": "get_api_school_teachers_id_timetable",
                "tags": [
                    "School: Teachers"
                ],
                "summary": "Teacher's weekly timetable",
                "description": "One teacher's week, for the workload drawer.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTeacherController@timetable",
                "x-source": "app/Http/Controllers/SchoolTeacherController.php#L139-L165",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "TeacherPolicy"
                    }
                ],
                "x-models": [
                    "Teacher",
                    "TimetableSlot"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Teacher id."
                    },
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`teacher_name`, `days` (slots per weekday), `total`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "teacher_name": {},
                                        "days": {},
                                        "total": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/teachers/{id}/update": {
            "post": {
                "operationId": "post_api_school_teachers_id_update",
                "tags": [
                    "School: Teachers"
                ],
                "summary": "Update a teacher",
                "description": "Updates a teacher with the same fields as creation (multipart; send `image` to replace the photo or `remove_image=1` to clear it).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTeacherController@update",
                "x-source": "app/Http/Controllers/SchoolTeacherController.php#L89-L109",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "TeacherPolicy"
                    }
                ],
                "x-models": [
                    "Teacher"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Teacher id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Address."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "employee_code": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Staff code."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "employees,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:employees,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Linked HR employee."
                                    },
                                    "gender": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "male",
                                            "female",
                                            "other"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:male,female,other"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Gender."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 5120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "image",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Photo."
                                    },
                                    "is_active": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active."
                                    },
                                    "joining_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Joining date."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "qualification": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Qualification."
                                    },
                                    "remove_image": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remove photo.",
                                        "type": "boolean"
                                    },
                                    "salary": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Salary."
                                    },
                                    "specialization": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Specialisation."
                                    }
                                },
                                "required": [
                                    "gender",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "employee_code": {},
                                        "employee_id": {},
                                        "gender": {},
                                        "phone": {},
                                        "email": {},
                                        "qualification": {},
                                        "specialization": {},
                                        "joining_date": {},
                                        "salary": {},
                                        "address": {},
                                        "notes": {},
                                        "is_active": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/timetable": {
            "get": {
                "operationId": "get_api_school_timetable",
                "tags": [
                    "School: Timetable"
                ],
                "summary": "Timetable",
                "description": "Timetable slots grouped by day of week for a class/section, teacher or the whole academic year. Each slot has subject, teacher, room, start and end time.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTimetableController@index",
                "x-source": "app/Http/Controllers/SchoolTimetableController.php#L21-L45",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "TimetableSlotPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "TimetableSlot"
                ],
                "parameters": [
                    {
                        "name": "academic_year_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Year (default current)."
                    },
                    {
                        "name": "class_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Class."
                    },
                    {
                        "name": "section_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Section."
                    },
                    {
                        "name": "teacher_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Teacher."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`days` (slots per weekday), `slots[]`, `total`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "days": {},
                                        "slots": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_timetable",
                "tags": [
                    "School: Timetable"
                ],
                "summary": "Add a timetable slot",
                "description": "Refused when the class/section or the teacher already has a slot overlapping that time.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTimetableController@store",
                "x-source": "app/Http/Controllers/SchoolTimetableController.php#L47-L60",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "TimetableSlotPolicy"
                    }
                ],
                "x-models": [
                    "TimetableSlot"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "day_of_week": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "mon",
                                            "tue",
                                            "wed",
                                            "thu",
                                            "fri",
                                            "sat",
                                            "sun"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:mon,tue,wed,thu,fri,sat,sun"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`mon`..`sun`."
                                    },
                                    "end_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "x-rules": [
                                            "after:start_time"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "date_format:H:i",
                                            "after:start_time"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`HH:MM` (after start)."
                                    },
                                    "room": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Room."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Section."
                                    },
                                    "start_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "x-laravel-rules": [
                                            "required",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`HH:MM`."
                                    },
                                    "subject_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "subjects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:subjects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject."
                                    },
                                    "teacher_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "teachers,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:teachers,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Teacher."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "day_of_week",
                                    "end_time",
                                    "start_time",
                                    "subject_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_year_id": {},
                                        "class_id": {},
                                        "section_id": {},
                                        "subject_id": {},
                                        "teacher_id": {},
                                        "day_of_week": {},
                                        "start_time": {},
                                        "end_time": {},
                                        "room": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/timetable/{id}": {
            "delete": {
                "operationId": "delete_api_school_timetable_id",
                "tags": [
                    "School: Timetable"
                ],
                "summary": "Delete a timetable slot",
                "description": "Deletes a timetable slot.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTimetableController@destroy",
                "x-source": "app/Http/Controllers/SchoolTimetableController.php#L78-L85",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "TimetableSlotPolicy"
                    }
                ],
                "x-models": [
                    "TimetableSlot"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Slot id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_timetable_id",
                "tags": [
                    "School: Timetable"
                ],
                "summary": "Update a timetable slot",
                "description": "Updates a slot with the same fields and clash detection as creation (teacher or room double-booking returns 422).",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolTimetableController@update",
                "x-source": "app/Http/Controllers/SchoolTimetableController.php#L62-L76",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "TimetableSlotPolicy"
                    }
                ],
                "x-models": [
                    "TimetableSlot"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Slot id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "academic_year_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Year."
                                    },
                                    "class_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "school_classes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:school_classes,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Class."
                                    },
                                    "day_of_week": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "mon",
                                            "tue",
                                            "wed",
                                            "thu",
                                            "fri",
                                            "sat",
                                            "sun"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:mon,tue,wed,thu,fri,sat,sun"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`mon`..`sun`."
                                    },
                                    "end_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "x-rules": [
                                            "after:start_time"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "date_format:H:i",
                                            "after:start_time"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`HH:MM` (after start)."
                                    },
                                    "room": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Room."
                                    },
                                    "section_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "class_sections,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:class_sections,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Section."
                                    },
                                    "start_time": {
                                        "type": "string",
                                        "x-format": "date (H:i)",
                                        "x-laravel-rules": [
                                            "required",
                                            "date_format:H:i"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`HH:MM`."
                                    },
                                    "subject_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "subjects,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:subjects,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Subject."
                                    },
                                    "teacher_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "teachers,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:teachers,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Teacher."
                                    }
                                },
                                "required": [
                                    "class_id",
                                    "day_of_week",
                                    "end_time",
                                    "start_time",
                                    "subject_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "academic_year_id": {},
                                        "class_id": {},
                                        "section_id": {},
                                        "subject_id": {},
                                        "teacher_id": {},
                                        "day_of_week": {},
                                        "start_time": {},
                                        "end_time": {},
                                        "room": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/years": {
            "get": {
                "operationId": "get_api_school_years",
                "tags": [
                    "School: Academics"
                ],
                "summary": "List academic years",
                "description": "Academic years with start/end dates, current and locked flags.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@years",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L29-L50",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "StudentEnrollment"
                ],
                "responses": {
                    "200": {
                        "description": "`academic_years[] {id, name, start_date, end_date, is_current, is_locked, enrollments}` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "academic_years": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_school_years",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Create an academic year",
                "description": "Setting `is_current` clears the flag on other years.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@storeYear",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L52-L61",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-rules": [
                                            "after:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "date",
                                            "after:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End (after start)."
                                    },
                                    "is_current": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Current year."
                                    },
                                    "is_locked": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Lock against changes."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. `2026/2027`)."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    }
                                },
                                "required": [
                                    "end_date",
                                    "name",
                                    "start_date"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "start_date": {},
                                        "end_date": {},
                                        "is_current": {},
                                        "is_locked": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/school/years/{id}": {
            "delete": {
                "operationId": "delete_api_school_years_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Delete an academic year",
                "description": "Deletes an academic year that has no enrolments.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@destroyYear",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L75-L91",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear",
                    "StudentEnrollment"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Year id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Has enrolments.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "This year has {$enrolled} enrolment(s). Delete those first, or lock the year instead."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_school_years_id",
                "tags": [
                    "School: Academics"
                ],
                "summary": "Update an academic year",
                "description": "Updates an academic year; setting `is_current` unsets it on the others, `is_locked` prevents further changes to its data.",
                "x-section": "Industry Modules",
                "x-surface": "admin",
                "x-controller": "SchoolAcademicController@updateYear",
                "x-source": "app/Http/Controllers/SchoolAcademicController.php#L63-L73",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SchoolClassPolicy"
                    }
                ],
                "x-models": [
                    "AcademicYear"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Year id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-rules": [
                                            "after:start_date"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "date",
                                            "after:start_date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End (after start)."
                                    },
                                    "is_current": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Current year."
                                    },
                                    "is_locked": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Lock against changes."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name (e.g. `2026/2027`)."
                                    },
                                    "start_date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    }
                                },
                                "required": [
                                    "end_date",
                                    "name",
                                    "start_date"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "name": {},
                                        "start_date": {},
                                        "end_date": {},
                                        "is_current": {},
                                        "is_locked": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/security/login-activity-report": {
            "get": {
                "operationId": "get_api_security_login_activity_report",
                "tags": [
                    "Security Settings"
                ],
                "summary": "Login activity report",
                "description": "Paginated history of the calling user's logins, including revoked/expired sessions, newest first.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SecuritySettingsController@loginActivityReport",
                "x-source": "app/Http/Controllers/SecuritySettingsController.php#L261-L332",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "report_device_management",
                        "slug": "report_device_management",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "UserLoginSession",
                    "OauthAccessToken"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{sessions: [{token_id, device, ip_address, login_at, last_activity_at, revoked_at, is_active, is_current}], totalRows}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "token_id": {
                                            "type": "string"
                                        },
                                        "device": {},
                                        "ip_address": {},
                                        "login_at": {},
                                        "last_activity_at": {},
                                        "revoked_at": {},
                                        "is_active": {},
                                        "is_current": {},
                                        "sessions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/security/sessions": {
            "get": {
                "operationId": "get_api_security_sessions",
                "tags": [
                    "Security Settings"
                ],
                "summary": "List active sessions",
                "description": "Every live session across all users: unrevoked, unexpired Passport tokens plus cookie sessions, joined with device/IP/login time from `user_login_sessions`. `is_current` marks the caller's own session.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SecuritySettingsController@sessions",
                "x-source": "app/Http/Controllers/SecuritySettingsController.php#L24-L112",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "login_device_management",
                        "slug": "login_device_management | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "OauthAccessToken",
                    "UserLoginSession",
                    "User"
                ],
                "responses": {
                    "200": {
                        "description": "`{sessions: [{token_id, user_id, user_name, device, ip_address, login_at, last_activity_at, is_current, expires_at}]}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "token_id": {
                                            "type": "string"
                                        },
                                        "user_id": {
                                            "type": "integer"
                                        },
                                        "user_name": {},
                                        "device": {},
                                        "ip_address": {},
                                        "login_at": {},
                                        "last_activity_at": {},
                                        "is_current": {},
                                        "expires_at": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "sessions": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/security/sessions/logout-other": {
            "post": {
                "operationId": "post_api_security_sessions_logout_other",
                "tags": [
                    "Security Settings"
                ],
                "summary": "Log out all other devices",
                "description": "Revokes every other session of the calling user and returns how many were revoked.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SecuritySettingsController@logoutAllOtherDevices",
                "x-source": "app/Http/Controllers/SecuritySettingsController.php#L170-L219",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "login_device_management",
                        "slug": "login_device_management | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "OauthAccessToken",
                    "UserLoginSession",
                    "OauthRefreshToken"
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, revoked: integer}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "revoked": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "The current session could not be identified.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Unable to identify the current session."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/security/sessions/{tokenId}": {
            "delete": {
                "operationId": "delete_api_security_sessions_tokenId",
                "tags": [
                    "Security Settings"
                ],
                "summary": "Log out a session",
                "description": "Revokes one session: for token sessions the access and refresh tokens are revoked; for `cookie:*` sessions the login session is marked revoked and the timeout middleware blocks further requests. The current session cannot be revoked here.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SecuritySettingsController@logoutSession",
                "x-source": "app/Http/Controllers/SecuritySettingsController.php#L114-L168",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "login_device_management",
                        "slug": "login_device_management | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "UserLoginSession",
                    "OauthAccessToken",
                    "OauthRefreshToken"
                ],
                "parameters": [
                    {
                        "name": "tokenId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Session key from the sessions list (Passport token ID or `cookie:<hash>`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Attempted to log out the current session.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "You cannot logout the current session from this list."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/serial_numbers": {
            "get": {
                "operationId": "get_api_serial_numbers",
                "tags": [
                    "Serial Numbers"
                ],
                "summary": "List serial numbers",
                "description": "Paginated serial / IMEI units restricted to the caller's warehouses. Rows: `id, serial_number, product_id, product_name, product_code, variant_name, warehouse_id, warehouse_name, status, provider_name (purchased from), client_name (sold to), cost, created_at`. `search` matches the serial number. Sort fields allowed: `id, serial_number, status, created_at`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SerialNumberController@index",
                "x-source": "app/Http/Controllers/SerialNumberController.php#L18-L87",
                "x-route-name": "serial_numbers.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ProductSerialPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProductSerial",
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only serials of this product."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only serials with this status (`available`, `sold`, `returned`, `damaged`, `reserved`…)."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only serials in this warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`serials[]`, `totalRows`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "serials": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/serial_numbers/available": {
            "get": {
                "operationId": "get_api_serial_numbers_available",
                "tags": [
                    "Serial Numbers"
                ],
                "summary": "List available serials for a sale",
                "description": "Serials with status `available` for a product (and optional variant) in a warehouse — the picker used when adding a serialised product to a sale or POS ticket. Pass `include_sale_id` when editing a sale so the serials already attached to that sale stay selectable. Requires `Sales_add`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SerialNumberController@available",
                "x-source": "app/Http/Controllers/SerialNumberController.php#L181-L200",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "include_sale_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sale being edited whose serials should be included."
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product id (required)."
                    },
                    {
                        "name": "product_variant_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Variant id."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Warehouse id (required; must be assigned to the caller)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`serials[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "serials": {}
                                    }
                                },
                                "example": {
                                    "serials": [
                                        {
                                            "id": 41,
                                            "serial_number": "IMEI-3567890",
                                            "status": "available"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/serial_numbers/for_purchase": {
            "get": {
                "operationId": "get_api_serial_numbers_for_purchase",
                "tags": [
                    "Serial Numbers"
                ],
                "summary": "List serials received on a purchase",
                "description": "Serials still `available` that came in with `purchase_id` — the picker for a purchase return. Requires `Purchase_Returns_add`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SerialNumberController@forPurchase",
                "x-source": "app/Http/Controllers/SerialNumberController.php#L224-L236",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchase_Returns_add",
                        "policy": "PurchaseReturnPolicy"
                    }
                ],
                "x-models": [
                    "ProductSerial"
                ],
                "parameters": [
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Limit to one product."
                    },
                    {
                        "name": "product_variant_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Limit to one variant."
                    },
                    {
                        "name": "purchase_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Purchase id (required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`serials[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "serials": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/serial_numbers/for_sale": {
            "get": {
                "operationId": "get_api_serial_numbers_for_sale",
                "tags": [
                    "Serial Numbers"
                ],
                "summary": "List serials sold on a sale",
                "description": "Serials with status `sold` that were sold on `sale_id` — the picker for a sale return. Requires `Sales_add`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SerialNumberController@forSale",
                "x-source": "app/Http/Controllers/SerialNumberController.php#L206-L218",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "ProductSerial"
                ],
                "parameters": [
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Limit to one product."
                    },
                    {
                        "name": "product_variant_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Limit to one variant."
                    },
                    {
                        "name": "sale_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sale id (required)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`serials[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "serials": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/serial_numbers/{id}/status": {
            "post": {
                "operationId": "post_api_serial_numbers_id_status",
                "tags": [
                    "Serial Numbers"
                ],
                "summary": "Change a serial's status manually",
                "description": "Sets the status (`available`, `damaged`, `reserved`…) and records a manual movement with the optional `notes`. The serial's warehouse must be assigned to the caller.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SerialNumberController@changeStatus",
                "x-source": "app/Http/Controllers/SerialNumberController.php#L141-L153",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ProductSerialPolicy"
                    }
                ],
                "x-models": [
                    "ProductSerial"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Serial record id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason / comment stored on the movement."
                                    },
                                    "status": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New status."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            },
                            "example": {
                                "status": "damaged",
                                "notes": "Screen cracked in stock"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/serial_numbers/{serial_number}": {
            "get": {
                "operationId": "get_api_serial_numbers_serial_number",
                "tags": [
                    "Serial Numbers"
                ],
                "summary": "Get a serial with its history",
                "description": "The serial record plus its ordered `movements[]` log: `action, from_status, to_status, warehouse_id, reference_type, reference_id, reference_ref (document Ref), user_name, created_at`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SerialNumberController@show",
                "x-source": "app/Http/Controllers/SerialNumberController.php#L92-L136",
                "x-route-name": "serial_numbers.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ProductSerialPolicy"
                    }
                ],
                "x-models": [
                    "ProductSerial",
                    "ProductSerialMovement",
                    "User"
                ],
                "parameters": [
                    {
                        "name": "serial_number",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Serial record id (not the serial string)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`serial` object and `movements[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "serial": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "integer"
                                                },
                                                "serial_number": {},
                                                "status": {},
                                                "product_name": {},
                                                "product_code": {},
                                                "variant_name": {},
                                                "warehouse_name": {},
                                                "provider_name": {},
                                                "client_name": {},
                                                "cost": {},
                                                "created_at": {
                                                    "type": "string"
                                                }
                                            }
                                        },
                                        "movements": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_checklist/categories": {
            "get": {
                "operationId": "get_api_service_checklist_categories",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "List checklist categories",
                "description": "With `items_count`. Paginated only when `limit` > 0; otherwise returns all rows for select boxes.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@categoriesIndex",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L13-L46",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ServiceChecklistCategory"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`categories[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "categories": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_service_checklist_categories",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "Create a checklist category",
                "description": "Creates a checklist category (e.g. *Intake inspection*) that groups checklist items shown on service jobs.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@categoriesStore",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L48-L65",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceChecklistCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag (default true)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name (max 191)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and `data`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_checklist/categories/{id}": {
            "delete": {
                "operationId": "delete_api_service_checklist_categories_id",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "Delete a checklist category",
                "description": "Deletes a category and its items.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@categoriesDestroy",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L84-L92",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceChecklistCategory"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_service_checklist_categories_id",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "Update a checklist category",
                "description": "Renames a category or changes its order/active flag.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@categoriesUpdate",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L67-L82",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceChecklistCategory"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_checklist/items": {
            "get": {
                "operationId": "get_api_service_checklist_items",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "List checklist items",
                "description": "Ordered by `sort_order` then name. Paginated only when `limit` > 0.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@itemsIndex",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L95-L130",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ServiceChecklistItem"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "category_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category filter."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`items[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_service_checklist_items",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "Create a checklist item",
                "description": "Adds an item to a checklist category (label, order, active flag).",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@itemsStore",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L132-L153",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceChecklistItem"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name (max 191)."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order (default 0)."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and `data`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_checklist/items/{id}": {
            "delete": {
                "operationId": "delete_api_service_checklist_items_id",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "Delete a checklist item",
                "description": "Deletes a checklist item.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@itemsDestroy",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L174-L182",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceChecklistItem"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Item id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_service_checklist_items_id",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "Update a checklist item",
                "description": "Updates a checklist item.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@itemsUpdate",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L155-L172",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceChecklistItem"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Item id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Category."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_checklist/options": {
            "get": {
                "operationId": "get_api_service_checklist_options",
                "tags": [
                    "Service Checklists"
                ],
                "summary": "Checklist options for the job form",
                "description": "Active categories, each with its active `items[]` — the structure used to build the intake checklist.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceChecklistController@options",
                "x-source": "app/Http/Controllers/ServiceChecklistController.php#L185-L223",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceChecklistCategory",
                    "ServiceChecklistItem"
                ],
                "responses": {
                    "200": {
                        "description": "`categories[] {id, name, description, items[]}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "description": {},
                                        "sort_order": {},
                                        "categories": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_job_pdf/{id}": {
            "get": {
                "operationId": "get_api_service_job_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Service job work-order PDF",
                "description": "Work order / invoice for a service job: customer, device, technician, parts, labour and totals. Requires the `view` permission on service jobs.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "ServiceJobController@service_job_pdf",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L1110-L1123",
                "x-middleware": [
                    "api"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Service job ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file `Service_Job_<id>.pdf`."
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/service_jobs": {
            "get": {
                "operationId": "get_api_service_jobs",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "List service jobs",
                "description": "Paginated jobs joined with `client_name`, `technician_name`. Sortable: `id, Ref, scheduled_date, status, job_type, payment_status, total_amount`. `search` matches Ref, service item, device brand/model/serial/IMEI or client name.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@index",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L35-L146",
                "x-route-name": "service_jobs.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "client_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Customer filter."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled date from."
                    },
                    {
                        "name": "job_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Free-text job type (e.g. `repair`, `maintenance`)."
                    },
                    {
                        "name": "payment_status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`unpaid`, `partial`, `paid`."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Job status."
                    },
                    {
                        "name": "technician_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Technician filter."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Scheduled date to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`jobs[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "jobs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_service_jobs",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Create a service job",
                "description": "Creates the job with an auto-generated `Ref`, copies the checklist rows, saves the billable items and recomputes totals. A job created directly as `delivered` deducts part stock immediately. Returns HTTP **201**.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@store",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L183-L213",
                "x-route-name": "service_jobs.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "accessories": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Accessories handed in (list of strings).",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "checklist": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "category_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checklist category id."
                                                },
                                                "category_name": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Category label (copied)."
                                                },
                                                "is_completed": {
                                                    "type": "boolean",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "boolean"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checked flag."
                                                },
                                                "item_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checklist item id."
                                                },
                                                "item_name": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "x-conditional": [
                                                        "required_with:checklist"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:checklist",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Item label (copied)."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Intake checklist rows."
                                    },
                                    "client_id": {
                                        "type": "integer",
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer."
                                    },
                                    "completed_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Actual completion."
                                    },
                                    "condition_on_arrival": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Condition notes at intake."
                                    },
                                    "device_brand": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Brand."
                                    },
                                    "device_color": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Colour."
                                    },
                                    "device_imei": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "IMEI."
                                    },
                                    "device_model": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Model."
                                    },
                                    "device_password": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unlock code left by the customer."
                                    },
                                    "device_serial": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Serial number."
                                    },
                                    "diagnosis": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Technician's diagnosis."
                                    },
                                    "diagnostic_fee": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Diagnostic fee amount."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "description": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "x-conditional": [
                                                        "required_with:items"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:items",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Line description."
                                                },
                                                "discount": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Discount value."
                                                },
                                                "discount_method": {
                                                    "type": "string",
                                                    "enum": [
                                                        "1",
                                                        "2"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:1,2"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`1` = percent, `2` = fixed."
                                                },
                                                "id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Existing line id (update)."
                                                },
                                                "notes": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Line notes."
                                                },
                                                "product_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product (parts)."
                                                },
                                                "product_variant_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Variant."
                                                },
                                                "quantity": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity."
                                                },
                                                "tax_method": {
                                                    "type": "string",
                                                    "enum": [
                                                        "1",
                                                        "2"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:1,2"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`1` = exclusive, `2` = inclusive."
                                                },
                                                "tax_rate": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Tax %."
                                                },
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "part",
                                                        "labor",
                                                        "other"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:part,labor,other"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`part`, `labor` or `other`."
                                                },
                                                "unit_price": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Unit price."
                                                },
                                                "warehouse_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Warehouse the part is taken from."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Billable lines."
                                    },
                                    "job_type": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Free-text type."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Internal notes."
                                    },
                                    "parent_job_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "service_jobs,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:service_jobs,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Parent job (re-work / warranty return)."
                                    },
                                    "quote_amount": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Quoted price."
                                    },
                                    "quote_valid_until": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Quote expiry."
                                    },
                                    "reported_issue": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer's description of the fault."
                                    },
                                    "scheduled_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Planned start."
                                    },
                                    "scheduled_end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Planned completion (>= start)."
                                    },
                                    "service_item": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "What is being serviced (e.g. `iPhone 13`)."
                                    },
                                    "started_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Actual start."
                                    },
                                    "status": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Initial status (default `pending`)."
                                    },
                                    "technician_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "service_technicians,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:service_technicians,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Technician."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse used for parts."
                                    },
                                    "warranty_days": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 3650,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:3650"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warranty period after delivery (default 30)."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "service_item"
                                ]
                            },
                            "example": {
                                "client_id": 4,
                                "service_item": "iPhone 13",
                                "job_type": "repair",
                                "status": "intake",
                                "technician_id": 2,
                                "warehouse_id": 1,
                                "device_brand": "Apple",
                                "device_model": "iPhone 13",
                                "device_imei": "356789012345678",
                                "reported_issue": "Cracked screen",
                                "quote_amount": 180,
                                "quote_valid_until": "2026-09-20",
                                "scheduled_date": "2026-09-08",
                                "warranty_days": 90,
                                "accessories": [
                                    "case",
                                    "charger"
                                ],
                                "checklist": [
                                    {
                                        "category_id": 1,
                                        "category_name": "Screen",
                                        "item_id": 3,
                                        "item_name": "Cracked",
                                        "is_completed": true
                                    }
                                ],
                                "items": [
                                    {
                                        "type": "part",
                                        "product_id": 120,
                                        "warehouse_id": 1,
                                        "description": "OLED screen",
                                        "quantity": 1,
                                        "unit_price": 140,
                                        "tax_rate": 20,
                                        "tax_method": "1"
                                    },
                                    {
                                        "type": "labor",
                                        "description": "Screen replacement",
                                        "quantity": 1,
                                        "unit_price": 40
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and new `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/create": {
            "get": {
                "operationId": "get_api_service_jobs_create",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Create-form data for a service job",
                "description": "Lookups: `clients`, active `technicians`, `warehouses`, active `payment_methods`, plus the allowed `statuses` and `payment_statuses`.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@create",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L149-L180",
                "x-route-name": "service_jobs.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "ServiceTechnician",
                    "Warehouse",
                    "PaymentMethod"
                ],
                "responses": {
                    "200": {
                        "description": "Lookup lists.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "technicians": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "statuses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_statuses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{id}/approve_quote": {
            "post": {
                "operationId": "post_api_service_jobs_id_approve_quote",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Approve the quote",
                "description": "Sets status `approved`, stamps `quote_approved_at` and records who approved (defaults to the current user).",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@approveQuote",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L429-L451",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "approved_by": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Approver name (e.g. the customer)."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{id}/create_quotation": {
            "post": {
                "operationId": "post_api_service_jobs_id_create_quotation",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Create a quotation from the job",
                "description": "Copies the job's items into a regular Quotation (requires `Quotations_add`). Idempotent: if the job is already linked, returns the existing quotation with `duplicate: true`. Uses a warehouse the caller can access (preferring the items' warehouse).",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@createQuotation",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L1147-L1263",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    },
                    {
                        "ability": "create",
                        "slug": "Quotations_add",
                        "policy": "QuotationPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "Quotation",
                    "Setting",
                    "Warehouse",
                    "UserWarehouse",
                    "QuotationDetail"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`duplicate: true` with existing `quotation_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "duplicate": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "quotation_id": {},
                                        "Ref": {}
                                    }
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success`, `quotation_id`, `Ref`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "quotation_id": {},
                                        "Ref": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "No customer on the job or no accessible warehouse.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "No warehouse is accessible to your account; cannot create a quotation."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{id}/decline_quote": {
            "post": {
                "operationId": "post_api_service_jobs_id_decline_quote",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Decline the quote",
                "description": "Sets status `declined`.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@declineQuote",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L454-L463",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{id}/mark_delivered": {
            "post": {
                "operationId": "post_api_service_jobs_id_mark_delivered",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Mark the job delivered",
                "description": "Refused (`422`) while an outstanding balance remains. Otherwise deducts part stock, sets `delivered`, `delivered_at`, computes `warranty_until` and stores the optional pickup signature.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@markDelivered",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L466-L504",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "pickup_signature": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Signature / name of the person collecting."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and stock `warnings[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "warnings": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{service_job}": {
            "delete": {
                "operationId": "delete_api_service_jobs_service_job",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Delete a service job",
                "description": "Soft-deletes the job and restocks any parts that had been deducted.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@destroy",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L412-L426",
                "x-route-name": "service_jobs.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_service_jobs_service_job",
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Get a service job",
                "description": "The `job` (with client and technician, quotation link) plus its `checklist[]`, `items[]` (parts/labor with pricing, tax, `stock_deducted`), `payments[]` and `photos[]`.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@show",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L216-L361",
                "x-route-name": "service_jobs.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "Quotation"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`job`, `checklist[]`, `items[]`, `payments[]`, `photos[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "category_id": {},
                                        "item_id": {},
                                        "category_name": {},
                                        "item_name": {},
                                        "is_completed": {
                                            "type": "boolean"
                                        },
                                        "completed_at": {},
                                        "type": {},
                                        "product_id": {},
                                        "product_variant_id": {},
                                        "warehouse_id": {},
                                        "description": {},
                                        "quantity": {
                                            "type": "number"
                                        },
                                        "unit_price": {
                                            "type": "number"
                                        },
                                        "discount": {
                                            "type": "number"
                                        },
                                        "discount_method": {},
                                        "tax_rate": {
                                            "type": "number"
                                        },
                                        "tax_method": {},
                                        "total": {
                                            "type": "number"
                                        },
                                        "cost": {
                                            "type": "number"
                                        },
                                        "stock_deducted": {
                                            "type": "boolean"
                                        },
                                        "notes": {},
                                        "Ref": {},
                                        "date": {
                                            "type": "string"
                                        },
                                        "montant": {
                                            "type": "number"
                                        },
                                        "change": {
                                            "type": "number"
                                        },
                                        "payment_method_id": {},
                                        "payment_method": {},
                                        "account_id": {},
                                        "payment_kind": {},
                                        "stage": {},
                                        "path": {},
                                        "url": {
                                            "type": "string"
                                        },
                                        "original_name": {},
                                        "mime_type": {},
                                        "size": {},
                                        "caption": {},
                                        "created_at": {},
                                        "job": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "Ref": {},
                                                "client_id": {},
                                                "client_name": {},
                                                "technician_id": {},
                                                "technician_name": {},
                                                "warehouse_id": {},
                                                "service_item": {},
                                                "job_type": {},
                                                "status": {},
                                                "scheduled_date": {},
                                                "scheduled_end_date": {},
                                                "started_at": {},
                                                "completed_at": {},
                                                "notes": {},
                                                "device_brand": {},
                                                "device_model": {},
                                                "device_serial": {},
                                                "device_imei": {},
                                                "device_color": {},
                                                "device_password": {},
                                                "accessories": {},
                                                "condition_on_arrival": {},
                                                "reported_issue": {},
                                                "diagnosis": {},
                                                "diagnostic_fee": {
                                                    "type": "number"
                                                },
                                                "quote_amount": {
                                                    "type": "number"
                                                },
                                                "quote_valid_until": {
                                                    "type": "string"
                                                },
                                                "quote_approved_at": {},
                                                "quote_approved_by": {},
                                                "quotation_id": {},
                                                "quotation_ref": {},
                                                "total_amount": {
                                                    "type": "number"
                                                },
                                                "paid_amount": {
                                                    "type": "number"
                                                },
                                                "balance_due": {},
                                                "payment_status": {},
                                                "warranty_days": {
                                                    "type": "integer"
                                                },
                                                "warranty_expires_at": {
                                                    "type": "string"
                                                },
                                                "parent_job_id": {},
                                                "delivered_at": {},
                                                "pickup_signature": {}
                                            }
                                        },
                                        "checklist": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "photos": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_service_jobs_service_job",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Update a service job",
                "description": "Same payload as create. `checklist` / `items` are fully replaced only when present in the body. Moving the status to `delivered` stamps `delivered_at`, deducts part stock and returns any stock `warnings`.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@update",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L364-L409",
                "x-route-name": "service_jobs.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "accessories": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Accessories handed in (list of strings).",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "checklist": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "category_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checklist category id."
                                                },
                                                "category_name": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Category label (copied)."
                                                },
                                                "is_completed": {
                                                    "type": "boolean",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "boolean"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checked flag."
                                                },
                                                "item_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checklist item id."
                                                },
                                                "item_name": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "x-conditional": [
                                                        "required_with:checklist"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:checklist",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Item label (copied)."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Checklist rows (full replacement)."
                                    },
                                    "client_id": {
                                        "type": "integer",
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer."
                                    },
                                    "completed_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Actual completion."
                                    },
                                    "condition_on_arrival": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Condition notes at intake."
                                    },
                                    "device_brand": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Brand."
                                    },
                                    "device_color": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Colour."
                                    },
                                    "device_imei": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "IMEI."
                                    },
                                    "device_model": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Model."
                                    },
                                    "device_password": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unlock code left by the customer."
                                    },
                                    "device_serial": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Serial number."
                                    },
                                    "diagnosis": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Technician's diagnosis."
                                    },
                                    "diagnostic_fee": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Diagnostic fee amount."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "description": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "x-conditional": [
                                                        "required_with:items"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:items",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Line description."
                                                },
                                                "discount": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Discount value."
                                                },
                                                "discount_method": {
                                                    "type": "string",
                                                    "enum": [
                                                        "1",
                                                        "2"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:1,2"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`1` = percent, `2` = fixed."
                                                },
                                                "id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "ID of an existing job line to update. Omit to add a new line; existing lines not present in `items` are removed."
                                                },
                                                "notes": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Line notes."
                                                },
                                                "product_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product (parts)."
                                                },
                                                "product_variant_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Variant."
                                                },
                                                "quantity": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity."
                                                },
                                                "tax_method": {
                                                    "type": "string",
                                                    "enum": [
                                                        "1",
                                                        "2"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:1,2"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`1` = exclusive, `2` = inclusive."
                                                },
                                                "tax_rate": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Tax %."
                                                },
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "part",
                                                        "labor",
                                                        "other"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:part,labor,other"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`part`, `labor` or `other`."
                                                },
                                                "unit_price": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Unit price."
                                                },
                                                "warehouse_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Warehouse the part is taken from."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Billable lines (full replacement)."
                                    },
                                    "job_type": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Free-text type."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Internal notes."
                                    },
                                    "parent_job_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "service_jobs,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:service_jobs,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Parent job (re-work / warranty return)."
                                    },
                                    "quote_amount": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Quoted price."
                                    },
                                    "quote_valid_until": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Quote expiry."
                                    },
                                    "reported_issue": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer's description of the fault."
                                    },
                                    "scheduled_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Planned start."
                                    },
                                    "scheduled_end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Planned completion (>= start)."
                                    },
                                    "service_item": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Serviced item."
                                    },
                                    "started_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Actual start."
                                    },
                                    "status": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Status."
                                    },
                                    "technician_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "service_technicians,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:service_technicians,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Technician."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse used for parts."
                                    },
                                    "warranty_days": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 3650,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:3650"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warranty period after delivery (default 30)."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "service_item"
                                ]
                            },
                            "example": {
                                "client_id": 4,
                                "service_item": "iPhone 13",
                                "job_type": "repair",
                                "status": "intake",
                                "technician_id": 2,
                                "warehouse_id": 1,
                                "device_brand": "Apple",
                                "device_model": "iPhone 13",
                                "device_imei": "356789012345678",
                                "reported_issue": "Cracked screen",
                                "quote_amount": 180,
                                "quote_valid_until": "2026-09-20",
                                "scheduled_date": "2026-09-08",
                                "warranty_days": 90,
                                "accessories": [
                                    "case",
                                    "charger"
                                ],
                                "checklist": [
                                    {
                                        "category_id": 1,
                                        "category_name": "Screen",
                                        "item_id": 3,
                                        "item_name": "Cracked",
                                        "is_completed": true
                                    }
                                ],
                                "items": [
                                    {
                                        "type": "part",
                                        "product_id": 120,
                                        "warehouse_id": 1,
                                        "description": "OLED screen",
                                        "quantity": 1,
                                        "unit_price": 140,
                                        "tax_rate": 20,
                                        "tax_method": "1"
                                    },
                                    {
                                        "type": "labor",
                                        "description": "Screen replacement",
                                        "quantity": 1,
                                        "unit_price": 40
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `warnings[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "warnings": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_service_jobs_service_job",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Service Jobs"
                ],
                "summary": "Update a service job",
                "description": "Same payload as create. `checklist` / `items` are fully replaced only when present in the body. Moving the status to `delivered` stamps `delivered_at`, deducts part stock and returns any stock `warnings`.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobController@update",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L364-L409",
                "x-route-name": "service_jobs.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "accessories": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Accessories handed in (list of strings).",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "checklist": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "category_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checklist category id."
                                                },
                                                "category_name": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Category label (copied)."
                                                },
                                                "is_completed": {
                                                    "type": "boolean",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "boolean"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checked flag."
                                                },
                                                "item_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Checklist item id."
                                                },
                                                "item_name": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "x-conditional": [
                                                        "required_with:checklist"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:checklist",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Item label (copied)."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Checklist rows (full replacement)."
                                    },
                                    "client_id": {
                                        "type": "integer",
                                        "x-exists": "clients,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:clients,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer."
                                    },
                                    "completed_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Actual completion."
                                    },
                                    "condition_on_arrival": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Condition notes at intake."
                                    },
                                    "device_brand": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Brand."
                                    },
                                    "device_color": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Colour."
                                    },
                                    "device_imei": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "IMEI."
                                    },
                                    "device_model": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Model."
                                    },
                                    "device_password": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unlock code left by the customer."
                                    },
                                    "device_serial": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Serial number."
                                    },
                                    "diagnosis": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Technician's diagnosis."
                                    },
                                    "diagnostic_fee": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Diagnostic fee amount."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "description": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "x-conditional": [
                                                        "required_with:items"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required_with:items",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Line description."
                                                },
                                                "discount": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Discount value."
                                                },
                                                "discount_method": {
                                                    "type": "string",
                                                    "enum": [
                                                        "1",
                                                        "2"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:1,2"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`1` = percent, `2` = fixed."
                                                },
                                                "id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "ID of an existing job line to update. Omit to add a new line; existing lines not present in `items` are removed."
                                                },
                                                "notes": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Line notes."
                                                },
                                                "product_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product (parts)."
                                                },
                                                "product_variant_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Variant."
                                                },
                                                "quantity": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity."
                                                },
                                                "tax_method": {
                                                    "type": "string",
                                                    "enum": [
                                                        "1",
                                                        "2"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:1,2"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`1` = exclusive, `2` = inclusive."
                                                },
                                                "tax_rate": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Tax %."
                                                },
                                                "type": {
                                                    "type": "string",
                                                    "enum": [
                                                        "part",
                                                        "labor",
                                                        "other"
                                                    ],
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "in:part,labor,other"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`part`, `labor` or `other`."
                                                },
                                                "unit_price": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Unit price."
                                                },
                                                "warehouse_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Warehouse the part is taken from."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Billable lines (full replacement)."
                                    },
                                    "job_type": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Free-text type."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Internal notes."
                                    },
                                    "parent_job_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "service_jobs,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:service_jobs,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Parent job (re-work / warranty return)."
                                    },
                                    "quote_amount": {
                                        "type": "number",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Quoted price."
                                    },
                                    "quote_valid_until": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Quote expiry."
                                    },
                                    "reported_issue": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Customer's description of the fault."
                                    },
                                    "scheduled_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Planned start."
                                    },
                                    "scheduled_end_date": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:scheduled_date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Planned completion (>= start)."
                                    },
                                    "service_item": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Serviced item."
                                    },
                                    "started_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Actual start."
                                    },
                                    "status": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Status."
                                    },
                                    "technician_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "service_technicians,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:service_technicians,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Technician."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse used for parts."
                                    },
                                    "warranty_days": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 3650,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:3650"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warranty period after delivery (default 30)."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "service_item"
                                ]
                            },
                            "example": {
                                "client_id": 4,
                                "service_item": "iPhone 13",
                                "job_type": "repair",
                                "status": "intake",
                                "technician_id": 2,
                                "warehouse_id": 1,
                                "device_brand": "Apple",
                                "device_model": "iPhone 13",
                                "device_imei": "356789012345678",
                                "reported_issue": "Cracked screen",
                                "quote_amount": 180,
                                "quote_valid_until": "2026-09-20",
                                "scheduled_date": "2026-09-08",
                                "warranty_days": 90,
                                "accessories": [
                                    "case",
                                    "charger"
                                ],
                                "checklist": [
                                    {
                                        "category_id": 1,
                                        "category_name": "Screen",
                                        "item_id": 3,
                                        "item_name": "Cracked",
                                        "is_completed": true
                                    }
                                ],
                                "items": [
                                    {
                                        "type": "part",
                                        "product_id": 120,
                                        "warehouse_id": 1,
                                        "description": "OLED screen",
                                        "quantity": 1,
                                        "unit_price": 140,
                                        "tax_rate": 20,
                                        "tax_method": "1"
                                    },
                                    {
                                        "type": "labor",
                                        "description": "Screen replacement",
                                        "quantity": 1,
                                        "unit_price": 40
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `warnings[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "warnings": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/service_jobs/{service_job}/payments": {
            "get": {
                "operationId": "get_api_service_jobs_service_job_payments",
                "tags": [
                    "Service Job Payments"
                ],
                "summary": "List payments of a job",
                "description": "Payments ordered by date plus `totals` (`total_amount`, `paid_amount`, `balance`).",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobPaymentController@index",
                "x-source": "app/Http/Controllers/ServiceJobPaymentController.php#L17-L53",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "ServiceJobPayment"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`payments[]` and `totals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "Ref": {},
                                        "date": {
                                            "type": "string"
                                        },
                                        "montant": {
                                            "type": "number"
                                        },
                                        "change": {
                                            "type": "number"
                                        },
                                        "payment_method_id": {},
                                        "payment_method": {},
                                        "account_id": {},
                                        "payment_kind": {},
                                        "notes": {},
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totals": {
                                            "type": "object",
                                            "properties": {
                                                "total_amount": {
                                                    "type": "number"
                                                },
                                                "paid_amount": {
                                                    "type": "number"
                                                },
                                                "balance_due": {},
                                                "payment_status": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_service_jobs_service_job_payments",
                "tags": [
                    "Service Job Payments"
                ],
                "summary": "Record a payment",
                "description": "Adds a payment (`Ref` generated), credits the treasury account when given and recomputes the job's paid amount and payment status. `refund` amounts are subtracted.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobPaymentController@store",
                "x-source": "app/Http/Controllers/ServiceJobPaymentController.php#L56-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "ServiceJobPayment",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "accounts,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:accounts,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Treasury account."
                                    },
                                    "change": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Change returned (cash)."
                                    },
                                    "date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Payment date."
                                    },
                                    "montant": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Amount (> 0)."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_kind": {
                                        "type": "string",
                                        "enum": [
                                            "deposit",
                                            "payment",
                                            "refund"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "in:deposit,payment,refund"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`deposit`, `payment` (default) or `refund`."
                                    },
                                    "payment_method_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "payment_methods,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:payment_methods,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Payment method."
                                    }
                                },
                                "required": [
                                    "date",
                                    "montant"
                                ]
                            },
                            "example": {
                                "date": "2026-09-08",
                                "montant": 100,
                                "payment_method_id": 1,
                                "account_id": 1,
                                "payment_kind": "deposit"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{service_job}/payments/{id}": {
            "delete": {
                "operationId": "delete_api_service_jobs_service_job_payments_id",
                "tags": [
                    "Service Job Payments"
                ],
                "summary": "Delete a payment",
                "description": "Soft-deletes, reverses the account movement and recomputes totals.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobPaymentController@destroy",
                "x-source": "app/Http/Controllers/ServiceJobPaymentController.php#L157-L179",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "ServiceJobPayment",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Payment id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_service_jobs_service_job_payments_id",
                "tags": [
                    "Service Job Payments"
                ],
                "summary": "Update a payment",
                "description": "Reverses the old account movement, applies the new one and recomputes totals.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobPaymentController@update",
                "x-source": "app/Http/Controllers/ServiceJobPaymentController.php#L104-L154",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "ServiceJobPayment",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Payment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "account_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "accounts,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:accounts,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account."
                                    },
                                    "change": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Change."
                                    },
                                    "date": {
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Date."
                                    },
                                    "montant": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Amount."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "payment_kind": {
                                        "type": "string",
                                        "enum": [
                                            "deposit",
                                            "payment",
                                            "refund"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "in:deposit,payment,refund"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Kind."
                                    },
                                    "payment_method_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "payment_methods,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:payment_methods,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Method."
                                    }
                                },
                                "required": [
                                    "date",
                                    "montant"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{service_job}/photos": {
            "get": {
                "operationId": "get_api_service_jobs_service_job_photos",
                "tags": [
                    "Service Job Photos"
                ],
                "summary": "List photos of a job",
                "description": "Photos attached to the job (before/after) with URL, caption, type and upload date.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobPhotoController@index",
                "x-source": "app/Http/Controllers/ServiceJobPhotoController.php#L14-L39",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "ServiceJobPhoto"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`photos[] {id, stage, url, original_name, mime_type, size, caption, created_at}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "stage": {},
                                        "path": {},
                                        "url": {
                                            "type": "string"
                                        },
                                        "original_name": {},
                                        "mime_type": {},
                                        "size": {},
                                        "caption": {},
                                        "created_at": {},
                                        "photos": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_service_jobs_service_job_photos",
                "tags": [
                    "Service Job Photos"
                ],
                "summary": "Upload photos",
                "description": "Multipart; up to 10 MB per image.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobPhotoController@store",
                "x-source": "app/Http/Controllers/ServiceJobPhotoController.php#L42-L96",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "ServiceJobPhoto"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "caption": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Caption applied to all uploaded photos."
                                    },
                                    "photos": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "binary",
                                            "x-format": "image",
                                            "maxLength": 10240,
                                            "x-laravel-rules": [
                                                "file",
                                                "image",
                                                "max:10240"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "One or more image files."
                                    },
                                    "stage": {
                                        "type": "string",
                                        "enum": [
                                            "intake",
                                            "before",
                                            "after",
                                            "delivery"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "in:intake,before,after,delivery"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`intake` (default), `before`, `after`, `delivery`."
                                    }
                                },
                                "required": [
                                    "photos"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "201": {
                        "description": "`success` and `photos[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "photos": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_jobs/{service_job}/photos/{id}": {
            "delete": {
                "operationId": "delete_api_service_jobs_service_job_photos_id",
                "tags": [
                    "Service Job Photos"
                ],
                "summary": "Delete a photo",
                "description": "Deletes a photo and its file.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceJobPhotoController@destroy",
                "x-source": "app/Http/Controllers/ServiceJobPhotoController.php#L99-L119",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "ServiceJobPhoto"
                ],
                "parameters": [
                    {
                        "name": "service_job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Job id."
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Photo id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_quote_pdf/{id}": {
            "get": {
                "operationId": "get_api_service_quote_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Service repair quote PDF",
                "description": "Customer-facing repair quote for a service job. Requires the `view` permission on service jobs.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "ServiceJobController@service_quote_pdf",
                "x-source": "app/Http/Controllers/ServiceJobController.php#L1128-L1141",
                "x-middleware": [
                    "api"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceJob",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Service job ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file `Service_Quote_<id>.pdf`."
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/service_technicians": {
            "get": {
                "operationId": "get_api_service_technicians",
                "tags": [
                    "Service Technicians"
                ],
                "summary": "List technicians",
                "description": "Paginated; sortable `id, name, is_active`; `search` matches name, phone or email.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceTechnicianController@index",
                "x-source": "app/Http/Controllers/ServiceTechnicianController.php#L12-L57",
                "x-route-name": "service_technicians.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ServiceTechnician"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`technicians[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "technicians": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_service_technicians",
                "tags": [
                    "Service Technicians"
                ],
                "summary": "Create a technician",
                "description": "Creates a technician (name, contact, skills, linked user/employee, active flag).",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceTechnicianController@store",
                "x-source": "app/Http/Controllers/ServiceTechnicianController.php#L60-L81",
                "x-route-name": "service_technicians.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceTechnician"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active (default true)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/service_technicians/{service_technician}": {
            "delete": {
                "operationId": "delete_api_service_technicians_service_technician",
                "tags": [
                    "Service Technicians"
                ],
                "summary": "Delete a technician",
                "description": "Soft-deletes a technician; jobs keep their technician reference.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceTechnicianController@destroy",
                "x-source": "app/Http/Controllers/ServiceTechnicianController.php#L104-L112",
                "x-route-name": "service_technicians.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceTechnician"
                ],
                "parameters": [
                    {
                        "name": "service_technician",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Technician id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_service_technicians_service_technician",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Service Technicians"
                ],
                "summary": "Update a technician",
                "description": "Updates a technician with the same fields as creation.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceTechnicianController@update",
                "x-source": "app/Http/Controllers/ServiceTechnicianController.php#L84-L101",
                "x-route-name": "service_technicians.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceTechnician"
                ],
                "parameters": [
                    {
                        "name": "service_technician",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Technician id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_service_technicians_service_technician",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Service Technicians"
                ],
                "summary": "Update a technician",
                "description": "Updates a technician with the same fields as creation.",
                "x-section": "Service Jobs",
                "x-surface": "admin",
                "x-controller": "ServiceTechnicianController@update",
                "x-source": "app/Http/Controllers/ServiceTechnicianController.php#L84-L101",
                "x-route-name": "service_technicians.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "ServiceJobPolicy"
                    }
                ],
                "x-models": [
                    "ServiceTechnician"
                ],
                "parameters": [
                    {
                        "name": "service_technician",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Technician id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Notes."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/settings/calendar": {
            "get": {
                "operationId": "get_api_settings_calendar",
                "tags": [
                    "Store Settings"
                ],
                "summary": "Get Google Calendar settings",
                "description": "Connection state and OAuth credentials (secret masked) used by appointment sync.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SettingsApiController@showCalendar",
                "x-source": "app/Http/Controllers/Api/Store/SettingsApiController.php#L722-L746",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`google_calendar_connected`, connect / disconnect URLs, `client_id`, `client_secret_set`, `redirect_uri`, `calendar_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "google_calendar_connected": {},
                                        "google_calendar_connect_url": {
                                            "type": "string"
                                        },
                                        "google_calendar_disconnect_url": {
                                            "type": "string"
                                        },
                                        "google_calendar_client_id": {},
                                        "google_calendar_client_secret_set": {},
                                        "google_calendar_redirect_uri": {},
                                        "google_calendar_calendar_id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_settings_calendar",
                "tags": [
                    "Store Settings"
                ],
                "summary": "Save Google Calendar settings",
                "description": "An empty `google_calendar_client_secret` keeps the existing secret.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SettingsApiController@updateCalendar",
                "x-source": "app/Http/Controllers/Api/Store/SettingsApiController.php#L751-L770",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "google_calendar_calendar_id": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Target calendar id."
                                    },
                                    "google_calendar_client_id": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "OAuth client id."
                                    },
                                    "google_calendar_client_secret": {
                                        "type": "string",
                                        "maxLength": 65535,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:65535"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "OAuth client secret."
                                    },
                                    "google_calendar_redirect_uri": {
                                        "type": "string",
                                        "maxLength": 512,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:512"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "OAuth redirect URI."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Settings record not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/settings/dark-mode": {
            "get": {
                "operationId": "get_api_settings_dark_mode",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get dark-mode flag",
                "description": "Returns only the `dark_mode` boolean. Cheap enough to be called on every page load before the full settings bundle arrives.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@getDarkMode",
                "x-source": "app/Http/Controllers/SettingsController.php#L372-L380",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{dark_mode: boolean}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "dark_mode": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_settings_dark_mode",
                "tags": [
                    "System Settings"
                ],
                "summary": "Set dark-mode flag",
                "description": "Persists the global default theme without touching any other setting. Accepts `1`/`0`, `true`/`false` (string or native).",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@updateDarkMode",
                "x-source": "app/Http/Controllers/SettingsController.php#L388-L414",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "dark_mode": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Truthy to enable dark mode, falsy to disable.",
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "dark_mode"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, dark_mode: boolean}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "dark_mode": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/settings/dashboard-grid-layout": {
            "put": {
                "operationId": "put_api_settings_dashboard_grid_layout",
                "tags": [
                    "System Settings"
                ],
                "summary": "Save dashboard grid layout",
                "description": "Stores the drag/resize positions of dashboard widgets. Accepts either a JSON string or a JSON object/array (encoded server-side). Send `null` to reset to the default layout.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@updateDashboardGridLayout",
                "x-source": "app/Http/Controllers/SettingsController.php#L1031-L1045",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "dashboard_grid_layout": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Layout produced by the dashboard grid (array of `{i, x, y, w, h}` items) or `null`.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, dashboard_grid_layout}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "dashboard_grid_layout": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/settings/{id}": {
            "post": {
                "operationId": "post_api_settings_id",
                "tags": [
                    "System Settings"
                ],
                "summary": "Update global settings",
                "description": "Partial update of the settings row: every field is applied only when present in the request, so callers may send a single key. `logo` is an optional image upload (resized to fit 800×800 and stored under `public/images`). Boolean-ish fields accept `1`/`0`, `true`/`false`. Changing `default_language` also updates the `languages` table default; changing `currency` re-syncs the storefront settings. The response echoes the pharmacy-mode block so the UI can refresh dependent toggles.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@update",
                "x-source": "app/Http/Controllers/SettingsController.php#L24-L364",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Currency",
                    "StoreSetting",
                    "Language"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "ID of the settings row (always `1` on a standard install)."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "CompanyAdress": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company postal address (note the single-d spelling used by the API)."
                                    },
                                    "CompanyName": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Legal/trading company name printed on documents."
                                    },
                                    "CompanyPhone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company phone number printed on documents."
                                    },
                                    "adjustment_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for stock adjustments."
                                    },
                                    "allow_overselling": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow sales to push stock negative."
                                    },
                                    "auto_journal_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Post accounting journal entries automatically from documents."
                                    },
                                    "backup_cloud_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Upload database backups to cloud storage."
                                    },
                                    "backup_cloud_path": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remote folder/prefix for uploaded backups."
                                    },
                                    "backup_cloud_provider": {
                                        "type": "string",
                                        "enum": [
                                            "s3",
                                            "gdrive",
                                            "dropbox"
                                        ],
                                        "description": "Cloud backup provider.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "backup_dropbox_access_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Dropbox access token (write-only)."
                                    },
                                    "backup_dropbox_path": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Dropbox folder path for backups."
                                    },
                                    "backup_gdrive_access_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth access token (write-only)."
                                    },
                                    "backup_gdrive_client_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth client ID.",
                                        "type": "string"
                                    },
                                    "backup_gdrive_client_secret": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth client secret (write-only)."
                                    },
                                    "backup_gdrive_folder_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google Drive folder ID that receives backups.",
                                        "type": "string"
                                    },
                                    "backup_gdrive_refresh_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth refresh token (write-only)."
                                    },
                                    "backup_keep_local": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Keep the local copy after a successful cloud upload.",
                                        "type": "boolean"
                                    },
                                    "backup_s3_access_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 access key."
                                    },
                                    "backup_s3_bucket": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 bucket name."
                                    },
                                    "backup_s3_endpoint": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Custom S3-compatible endpoint URL."
                                    },
                                    "backup_s3_path_style": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Use path-style S3 URLs (needed for MinIO etc.).",
                                        "type": "boolean"
                                    },
                                    "backup_s3_region": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 region."
                                    },
                                    "backup_s3_secret_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 secret key (write-only; read back as `backup_s3_has_secret_key`)."
                                    },
                                    "block_expired_sale": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: refuse to sell expired batches.",
                                        "type": "boolean"
                                    },
                                    "client": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default customer (walk-in) pre-selected in POS and sales.",
                                        "type": "integer"
                                    },
                                    "company_name_ar": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Arabic company name, used on ZATCA / bilingual invoices."
                                    },
                                    "currency": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default currency.",
                                        "type": "integer"
                                    },
                                    "dark_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default theme (`1` dark, `0` light). See also `PUT /api/settings/dark-mode`.",
                                        "type": "boolean"
                                    },
                                    "dashboard_font_family": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Font family used on the dashboard."
                                    },
                                    "dashboard_font_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Base font size (px) used on the dashboard.",
                                        "type": "integer"
                                    },
                                    "dashboard_grid_layout": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON layout of dashboard widgets (see the dedicated endpoint).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "dashboard_section_order": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array ordering dashboard sections.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "date_format": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Display format for dates: `Y-m-d`, `d-m-Y`, `m-d-Y`, etc."
                                    },
                                    "debug_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable verbose error responses (development only).",
                                        "type": "boolean"
                                    },
                                    "default_account": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default finance account used for payments.",
                                        "type": "integer"
                                    },
                                    "default_dashboard_date_range": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default range for dashboard charts (e.g. `this_month`)."
                                    },
                                    "default_language": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Locale code of the default UI language (e.g. `en`, `ar`)."
                                    },
                                    "default_payment_method": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default payment method.",
                                        "type": "integer"
                                    },
                                    "default_tax": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default order tax percentage applied to new sales/purchases."
                                    },
                                    "developed_by": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Credit line shown in the UI footer."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company email; also the default recipient for test mails."
                                    },
                                    "enable_3_decimal_pricing": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Use three decimals for prices/quantities."
                                    },
                                    "enable_kitchen_display": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable the Kitchen Display System."
                                    },
                                    "enable_multi_currency": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow per-document currencies."
                                    },
                                    "enable_multi_pack_selling": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable multi-pack (unit conversion) selling."
                                    },
                                    "enable_pos_salesperson_switch": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow switching the salesperson inside POS."
                                    },
                                    "enable_wholesale_pricing": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable wholesale price tiers."
                                    },
                                    "expiry_warning_days": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: days before expiry at which a batch is flagged.",
                                        "type": "integer"
                                    },
                                    "export_settings": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON with export defaults (format, columns).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "footer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Footer text shown in the admin UI."
                                    },
                                    "hide_site_name": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide the app name next to the logo.",
                                        "type": "boolean"
                                    },
                                    "invoice_footer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text appended to printed invoices."
                                    },
                                    "invoice_format": {
                                        "type": "string",
                                        "enum": [
                                            "thermal",
                                            "a4"
                                        ],
                                        "description": "Global invoice layout.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "invoice_logo_height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Logo height (px) on A4 invoices.",
                                        "type": "integer"
                                    },
                                    "invoice_logo_width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Logo width (px) on A4 invoices.",
                                        "type": "integer"
                                    },
                                    "is_invoice_footer": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Whether the invoice footer text is printed."
                                    },
                                    "kitchen_auto_online_orders": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push online-store orders to the kitchen automatically.",
                                        "type": "boolean"
                                    },
                                    "kitchen_target_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Target preparation time shown on the KDS.",
                                        "type": "integer"
                                    },
                                    "logo": {
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Company logo image file (PNG/JPG). Omit to keep the current logo.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "offline_sync_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable POS offline sync."
                                    },
                                    "pharmacy_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable pharmacy features (batch expiry enforcement).",
                                        "type": "boolean"
                                    },
                                    "point_to_amount_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty: currency value of one point."
                                    },
                                    "price_format": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Number of decimals / thousands separator style used to format prices."
                                    },
                                    "print_expiry_on_receipt": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: print batch expiry dates on receipts.",
                                        "type": "boolean"
                                    },
                                    "product_image_max_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Max edge (px) when resizing product images.",
                                        "type": "integer"
                                    },
                                    "product_image_resize": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resize product images on upload.",
                                        "type": "boolean"
                                    },
                                    "purchase_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for purchases."
                                    },
                                    "purchase_return_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for purchase returns."
                                    },
                                    "quotation_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for quotations."
                                    },
                                    "quotation_with_stock": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reserve stock when a quotation is created.",
                                        "type": "boolean"
                                    },
                                    "rtl": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Force right-to-left layout.",
                                        "type": "boolean"
                                    },
                                    "sale_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for sales (default `SL_`)."
                                    },
                                    "sale_return_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for sale returns."
                                    },
                                    "session_timeout_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Idle minutes after which API tokens/sessions expire.",
                                        "type": "integer"
                                    },
                                    "show_language": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the language switcher in the top bar."
                                    },
                                    "show_product_gtin": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the GTIN field on products."
                                    },
                                    "show_serial_tracking": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show serial-number tracking on products."
                                    },
                                    "sidebar_logo_height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sidebar logo height in px.",
                                        "type": "integer"
                                    },
                                    "sidebar_logo_width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sidebar logo width in px.",
                                        "type": "integer"
                                    },
                                    "sidebar_show_logo": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the logo in the sidebar header.",
                                        "type": "boolean"
                                    },
                                    "sms_gateway": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Name of the SMS gateway used for notifications (`twilio`, `termi`, `infobip`, `custom`) or empty to disable."
                                    },
                                    "timezone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "PHP timezone identifier (e.g. `Asia/Riyadh`) used for all date display."
                                    },
                                    "transfer_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for stock transfers."
                                    },
                                    "vat_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax registration number (VAT/TRN) printed on invoices and embedded in the ZATCA QR."
                                    },
                                    "vehicle_fitment_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable the vehicle fitment (auto-parts) module."
                                    },
                                    "warehouse": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default warehouse pre-selected in stock documents.",
                                        "type": "integer"
                                    },
                                    "zatca_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable ZATCA e-invoicing."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true, pharmacy_mode, expiry_warning_days, block_expired_sale, print_expiry_on_receipt}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pharmacy_mode": {},
                                        "expiry_warning_days": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "block_expired_sale": {},
                                        "print_expiry_on_receipt": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_settings_setting",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "System Settings"
                ],
                "summary": "Update global settings (alias)",
                "description": "Identical to `POST /api/settings/{id}`; use POST when uploading a logo because multipart PUT is not reliably parsed by PHP.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@update",
                "x-source": "app/Http/Controllers/SettingsController.php#L24-L364",
                "x-route-name": "settings.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Currency",
                    "StoreSetting",
                    "Language"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "ID of the settings row (always `1` on a standard install)."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "CompanyAdress": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company postal address (note the single-d spelling used by the API)."
                                    },
                                    "CompanyName": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Legal/trading company name printed on documents."
                                    },
                                    "CompanyPhone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company phone number printed on documents."
                                    },
                                    "adjustment_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for stock adjustments."
                                    },
                                    "allow_overselling": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow sales to push stock negative."
                                    },
                                    "auto_journal_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Post accounting journal entries automatically from documents."
                                    },
                                    "backup_cloud_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Upload database backups to cloud storage."
                                    },
                                    "backup_cloud_path": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remote folder/prefix for uploaded backups."
                                    },
                                    "backup_cloud_provider": {
                                        "type": "string",
                                        "enum": [
                                            "s3",
                                            "gdrive",
                                            "dropbox"
                                        ],
                                        "description": "Cloud backup provider.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "backup_dropbox_access_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Dropbox access token (write-only)."
                                    },
                                    "backup_dropbox_path": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Dropbox folder path for backups."
                                    },
                                    "backup_gdrive_access_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth access token (write-only)."
                                    },
                                    "backup_gdrive_client_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth client ID.",
                                        "type": "string"
                                    },
                                    "backup_gdrive_client_secret": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth client secret (write-only)."
                                    },
                                    "backup_gdrive_folder_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google Drive folder ID that receives backups.",
                                        "type": "string"
                                    },
                                    "backup_gdrive_refresh_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth refresh token (write-only)."
                                    },
                                    "backup_keep_local": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Keep the local copy after a successful cloud upload.",
                                        "type": "boolean"
                                    },
                                    "backup_s3_access_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 access key."
                                    },
                                    "backup_s3_bucket": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 bucket name."
                                    },
                                    "backup_s3_endpoint": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Custom S3-compatible endpoint URL."
                                    },
                                    "backup_s3_path_style": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Use path-style S3 URLs (needed for MinIO etc.).",
                                        "type": "boolean"
                                    },
                                    "backup_s3_region": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 region."
                                    },
                                    "backup_s3_secret_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 secret key (write-only; read back as `backup_s3_has_secret_key`)."
                                    },
                                    "block_expired_sale": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: refuse to sell expired batches.",
                                        "type": "boolean"
                                    },
                                    "client": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default customer (walk-in) pre-selected in POS and sales.",
                                        "type": "integer"
                                    },
                                    "company_name_ar": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Arabic company name, used on ZATCA / bilingual invoices."
                                    },
                                    "currency": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default currency.",
                                        "type": "integer"
                                    },
                                    "dark_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default theme (`1` dark, `0` light). See also `PUT /api/settings/dark-mode`.",
                                        "type": "boolean"
                                    },
                                    "dashboard_font_family": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Font family used on the dashboard."
                                    },
                                    "dashboard_font_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Base font size (px) used on the dashboard.",
                                        "type": "integer"
                                    },
                                    "dashboard_grid_layout": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON layout of dashboard widgets (see the dedicated endpoint).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "dashboard_section_order": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array ordering dashboard sections.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "date_format": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Display format for dates: `Y-m-d`, `d-m-Y`, `m-d-Y`, etc."
                                    },
                                    "debug_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable verbose error responses (development only).",
                                        "type": "boolean"
                                    },
                                    "default_account": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default finance account used for payments.",
                                        "type": "integer"
                                    },
                                    "default_dashboard_date_range": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default range for dashboard charts (e.g. `this_month`)."
                                    },
                                    "default_language": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Locale code of the default UI language (e.g. `en`, `ar`)."
                                    },
                                    "default_payment_method": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default payment method.",
                                        "type": "integer"
                                    },
                                    "default_tax": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default order tax percentage applied to new sales/purchases."
                                    },
                                    "developed_by": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Credit line shown in the UI footer."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company email; also the default recipient for test mails."
                                    },
                                    "enable_3_decimal_pricing": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Use three decimals for prices/quantities."
                                    },
                                    "enable_kitchen_display": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable the Kitchen Display System."
                                    },
                                    "enable_multi_currency": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow per-document currencies."
                                    },
                                    "enable_multi_pack_selling": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable multi-pack (unit conversion) selling."
                                    },
                                    "enable_pos_salesperson_switch": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow switching the salesperson inside POS."
                                    },
                                    "enable_wholesale_pricing": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable wholesale price tiers."
                                    },
                                    "expiry_warning_days": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: days before expiry at which a batch is flagged.",
                                        "type": "integer"
                                    },
                                    "export_settings": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON with export defaults (format, columns).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "footer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Footer text shown in the admin UI."
                                    },
                                    "hide_site_name": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide the app name next to the logo.",
                                        "type": "boolean"
                                    },
                                    "invoice_footer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text appended to printed invoices."
                                    },
                                    "invoice_format": {
                                        "type": "string",
                                        "enum": [
                                            "thermal",
                                            "a4"
                                        ],
                                        "description": "Global invoice layout.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "invoice_logo_height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Logo height (px) on A4 invoices.",
                                        "type": "integer"
                                    },
                                    "invoice_logo_width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Logo width (px) on A4 invoices.",
                                        "type": "integer"
                                    },
                                    "is_invoice_footer": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Whether the invoice footer text is printed."
                                    },
                                    "kitchen_auto_online_orders": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push online-store orders to the kitchen automatically.",
                                        "type": "boolean"
                                    },
                                    "kitchen_target_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Target preparation time shown on the KDS.",
                                        "type": "integer"
                                    },
                                    "logo": {
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Company logo image file (PNG/JPG). Omit to keep the current logo.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "offline_sync_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable POS offline sync."
                                    },
                                    "pharmacy_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable pharmacy features (batch expiry enforcement).",
                                        "type": "boolean"
                                    },
                                    "point_to_amount_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty: currency value of one point."
                                    },
                                    "price_format": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Number of decimals / thousands separator style used to format prices."
                                    },
                                    "print_expiry_on_receipt": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: print batch expiry dates on receipts.",
                                        "type": "boolean"
                                    },
                                    "product_image_max_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Max edge (px) when resizing product images.",
                                        "type": "integer"
                                    },
                                    "product_image_resize": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resize product images on upload.",
                                        "type": "boolean"
                                    },
                                    "purchase_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for purchases."
                                    },
                                    "purchase_return_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for purchase returns."
                                    },
                                    "quotation_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for quotations."
                                    },
                                    "quotation_with_stock": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reserve stock when a quotation is created.",
                                        "type": "boolean"
                                    },
                                    "rtl": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Force right-to-left layout.",
                                        "type": "boolean"
                                    },
                                    "sale_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for sales (default `SL_`)."
                                    },
                                    "sale_return_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for sale returns."
                                    },
                                    "session_timeout_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Idle minutes after which API tokens/sessions expire.",
                                        "type": "integer"
                                    },
                                    "show_language": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the language switcher in the top bar."
                                    },
                                    "show_product_gtin": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the GTIN field on products."
                                    },
                                    "show_serial_tracking": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show serial-number tracking on products."
                                    },
                                    "sidebar_logo_height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sidebar logo height in px.",
                                        "type": "integer"
                                    },
                                    "sidebar_logo_width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sidebar logo width in px.",
                                        "type": "integer"
                                    },
                                    "sidebar_show_logo": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the logo in the sidebar header.",
                                        "type": "boolean"
                                    },
                                    "sms_gateway": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Name of the SMS gateway used for notifications (`twilio`, `termi`, `infobip`, `custom`) or empty to disable."
                                    },
                                    "timezone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "PHP timezone identifier (e.g. `Asia/Riyadh`) used for all date display."
                                    },
                                    "transfer_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for stock transfers."
                                    },
                                    "vat_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax registration number (VAT/TRN) printed on invoices and embedded in the ZATCA QR."
                                    },
                                    "vehicle_fitment_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable the vehicle fitment (auto-parts) module."
                                    },
                                    "warehouse": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default warehouse pre-selected in stock documents.",
                                        "type": "integer"
                                    },
                                    "zatca_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable ZATCA e-invoicing."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pharmacy_mode": {},
                                        "expiry_warning_days": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "block_expired_sale": {},
                                        "print_expiry_on_receipt": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_settings_setting",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "System Settings"
                ],
                "summary": "Update global settings (alias)",
                "description": "Identical to `POST /api/settings/{id}`; use POST when uploading a logo because multipart PUT is not reliably parsed by PHP.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@update",
                "x-source": "app/Http/Controllers/SettingsController.php#L24-L364",
                "x-route-name": "settings.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Currency",
                    "StoreSetting",
                    "Language"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "ID of the settings row (always `1` on a standard install)."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "CompanyAdress": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company postal address (note the single-d spelling used by the API)."
                                    },
                                    "CompanyName": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Legal/trading company name printed on documents."
                                    },
                                    "CompanyPhone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company phone number printed on documents."
                                    },
                                    "adjustment_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for stock adjustments."
                                    },
                                    "allow_overselling": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow sales to push stock negative."
                                    },
                                    "auto_journal_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Post accounting journal entries automatically from documents."
                                    },
                                    "backup_cloud_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Upload database backups to cloud storage."
                                    },
                                    "backup_cloud_path": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Remote folder/prefix for uploaded backups."
                                    },
                                    "backup_cloud_provider": {
                                        "type": "string",
                                        "enum": [
                                            "s3",
                                            "gdrive",
                                            "dropbox"
                                        ],
                                        "description": "Cloud backup provider.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "backup_dropbox_access_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Dropbox access token (write-only)."
                                    },
                                    "backup_dropbox_path": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Dropbox folder path for backups."
                                    },
                                    "backup_gdrive_access_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth access token (write-only)."
                                    },
                                    "backup_gdrive_client_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth client ID.",
                                        "type": "string"
                                    },
                                    "backup_gdrive_client_secret": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth client secret (write-only)."
                                    },
                                    "backup_gdrive_folder_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google Drive folder ID that receives backups.",
                                        "type": "string"
                                    },
                                    "backup_gdrive_refresh_token": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Google OAuth refresh token (write-only)."
                                    },
                                    "backup_keep_local": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Keep the local copy after a successful cloud upload.",
                                        "type": "boolean"
                                    },
                                    "backup_s3_access_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 access key."
                                    },
                                    "backup_s3_bucket": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 bucket name."
                                    },
                                    "backup_s3_endpoint": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Custom S3-compatible endpoint URL."
                                    },
                                    "backup_s3_path_style": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Use path-style S3 URLs (needed for MinIO etc.).",
                                        "type": "boolean"
                                    },
                                    "backup_s3_region": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 region."
                                    },
                                    "backup_s3_secret_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "S3 secret key (write-only; read back as `backup_s3_has_secret_key`)."
                                    },
                                    "block_expired_sale": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: refuse to sell expired batches.",
                                        "type": "boolean"
                                    },
                                    "client": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default customer (walk-in) pre-selected in POS and sales.",
                                        "type": "integer"
                                    },
                                    "company_name_ar": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Arabic company name, used on ZATCA / bilingual invoices."
                                    },
                                    "currency": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default currency.",
                                        "type": "integer"
                                    },
                                    "dark_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default theme (`1` dark, `0` light). See also `PUT /api/settings/dark-mode`.",
                                        "type": "boolean"
                                    },
                                    "dashboard_font_family": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Font family used on the dashboard."
                                    },
                                    "dashboard_font_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Base font size (px) used on the dashboard.",
                                        "type": "integer"
                                    },
                                    "dashboard_grid_layout": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON layout of dashboard widgets (see the dedicated endpoint).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "dashboard_section_order": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON array ordering dashboard sections.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "date_format": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Display format for dates: `Y-m-d`, `d-m-Y`, `m-d-Y`, etc."
                                    },
                                    "debug_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable verbose error responses (development only).",
                                        "type": "boolean"
                                    },
                                    "default_account": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default finance account used for payments.",
                                        "type": "integer"
                                    },
                                    "default_dashboard_date_range": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default range for dashboard charts (e.g. `this_month`)."
                                    },
                                    "default_language": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Locale code of the default UI language (e.g. `en`, `ar`)."
                                    },
                                    "default_payment_method": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default payment method.",
                                        "type": "integer"
                                    },
                                    "default_tax": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Default order tax percentage applied to new sales/purchases."
                                    },
                                    "developed_by": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Credit line shown in the UI footer."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Company email; also the default recipient for test mails."
                                    },
                                    "enable_3_decimal_pricing": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Use three decimals for prices/quantities."
                                    },
                                    "enable_kitchen_display": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable the Kitchen Display System."
                                    },
                                    "enable_multi_currency": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow per-document currencies."
                                    },
                                    "enable_multi_pack_selling": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable multi-pack (unit conversion) selling."
                                    },
                                    "enable_pos_salesperson_switch": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow switching the salesperson inside POS."
                                    },
                                    "enable_wholesale_pricing": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable wholesale price tiers."
                                    },
                                    "expiry_warning_days": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: days before expiry at which a batch is flagged.",
                                        "type": "integer"
                                    },
                                    "export_settings": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON with export defaults (format, columns).",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "footer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Footer text shown in the admin UI."
                                    },
                                    "hide_site_name": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide the app name next to the logo.",
                                        "type": "boolean"
                                    },
                                    "invoice_footer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text appended to printed invoices."
                                    },
                                    "invoice_format": {
                                        "type": "string",
                                        "enum": [
                                            "thermal",
                                            "a4"
                                        ],
                                        "description": "Global invoice layout.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "invoice_logo_height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Logo height (px) on A4 invoices.",
                                        "type": "integer"
                                    },
                                    "invoice_logo_width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Logo width (px) on A4 invoices.",
                                        "type": "integer"
                                    },
                                    "is_invoice_footer": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Whether the invoice footer text is printed."
                                    },
                                    "kitchen_auto_online_orders": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push online-store orders to the kitchen automatically.",
                                        "type": "boolean"
                                    },
                                    "kitchen_target_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Target preparation time shown on the KDS.",
                                        "type": "integer"
                                    },
                                    "logo": {
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Company logo image file (PNG/JPG). Omit to keep the current logo.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "offline_sync_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable POS offline sync."
                                    },
                                    "pharmacy_mode": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable pharmacy features (batch expiry enforcement).",
                                        "type": "boolean"
                                    },
                                    "point_to_amount_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Loyalty: currency value of one point."
                                    },
                                    "price_format": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Number of decimals / thousands separator style used to format prices."
                                    },
                                    "print_expiry_on_receipt": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Pharmacy mode: print batch expiry dates on receipts.",
                                        "type": "boolean"
                                    },
                                    "product_image_max_size": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Max edge (px) when resizing product images.",
                                        "type": "integer"
                                    },
                                    "product_image_resize": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resize product images on upload.",
                                        "type": "boolean"
                                    },
                                    "purchase_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for purchases."
                                    },
                                    "purchase_return_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for purchase returns."
                                    },
                                    "quotation_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for quotations."
                                    },
                                    "quotation_with_stock": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reserve stock when a quotation is created.",
                                        "type": "boolean"
                                    },
                                    "rtl": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Force right-to-left layout.",
                                        "type": "boolean"
                                    },
                                    "sale_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for sales (default `SL_`)."
                                    },
                                    "sale_return_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for sale returns."
                                    },
                                    "session_timeout_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Idle minutes after which API tokens/sessions expire.",
                                        "type": "integer"
                                    },
                                    "show_language": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the language switcher in the top bar."
                                    },
                                    "show_product_gtin": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the GTIN field on products."
                                    },
                                    "show_serial_tracking": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show serial-number tracking on products."
                                    },
                                    "sidebar_logo_height": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sidebar logo height in px.",
                                        "type": "integer"
                                    },
                                    "sidebar_logo_width": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sidebar logo width in px.",
                                        "type": "integer"
                                    },
                                    "sidebar_show_logo": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the logo in the sidebar header.",
                                        "type": "boolean"
                                    },
                                    "sms_gateway": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Name of the SMS gateway used for notifications (`twilio`, `termi`, `infobip`, `custom`) or empty to disable."
                                    },
                                    "timezone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "PHP timezone identifier (e.g. `Asia/Riyadh`) used for all date display."
                                    },
                                    "transfer_prefix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reference prefix for stock transfers."
                                    },
                                    "vat_number": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Tax registration number (VAT/TRN) printed on invoices and embedded in the ZATCA QR."
                                    },
                                    "vehicle_fitment_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable the vehicle fitment (auto-parts) module."
                                    },
                                    "warehouse": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "ID of the default warehouse pre-selected in stock documents.",
                                        "type": "integer"
                                    },
                                    "zatca_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable ZATCA e-invoicing."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pharmacy_mode": {},
                                        "expiry_warning_days": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "block_expired_sale": {},
                                        "print_expiry_on_receipt": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/shipments": {
            "get": {
                "operationId": "get_api_shipments",
                "tags": [
                    "Shipments"
                ],
                "summary": "List shipments",
                "description": "Paginated shipments joined with their sale. Rows: `id, date, shipment_ref, status, delivered_to, shipping_address, shipping_details, sale_ref, sale_id, client_name, warehouse_name`. `search` matches shipment Ref, status, recipient, sale Ref, warehouse and customer names. `status_counts` gives the number of shipments per status.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "ShipmentController@index",
                "x-source": "app/Http/Controllers/ShipmentController.php#L16-L93",
                "x-route-name": "shipments.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shipment",
                        "policy": "ShipmentPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Shipment"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`shipments[]`, `totalRows`, `status_counts`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "shipments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "status_counts": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_shipments",
                "tags": [
                    "Shipments"
                ],
                "summary": "Create or update a shipment",
                "description": "Upserts the shipment identified by `Ref` (use the Ref returned by *Get the shipment of a sale*) and sets the sale's `shipping_status` to `status`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "ShipmentController@store",
                "x-source": "app/Http/Controllers/ShipmentController.php#L97-L125",
                "x-route-name": "shipments.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "shipment",
                        "policy": "ShipmentPolicy"
                    }
                ],
                "x-models": [
                    "Shipment",
                    "Sale"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "Ref": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipment reference."
                                    },
                                    "delivered_to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Recipient name.",
                                        "type": "string"
                                    },
                                    "sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale id."
                                    },
                                    "shipping_address": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Delivery address."
                                    },
                                    "shipping_details": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Carrier / tracking notes."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Shipment status. Required."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            },
                            "example": {
                                "Ref": "SH_1112",
                                "sale_id": 41,
                                "status": "shipped",
                                "delivered_to": "Jane Doe",
                                "shipping_address": "12 Main St, Casablanca",
                                "shipping_details": "DHL 1Z999"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shipments/{shipment}": {
            "delete": {
                "operationId": "delete_api_shipments_shipment",
                "tags": [
                    "Shipments"
                ],
                "summary": "Delete a shipment",
                "description": "Deletes the shipment and sets the sale's `shipping_status` to the `status` query value.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "ShipmentController@destroy",
                "x-source": "app/Http/Controllers/ShipmentController.php#L184-L202",
                "x-route-name": "shipments.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "shipment",
                        "policy": "ShipmentPolicy"
                    }
                ],
                "x-models": [
                    "Shipment",
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "shipment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shipment id."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Shipping status to leave on the sale (e.g. `ordered`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_shipments_shipment",
                "tags": [
                    "Shipments"
                ],
                "summary": "Get the shipment of a sale",
                "description": "**The path parameter is the sale id**, not the shipment id. Returns the existing shipment for that sale, or a blank template with the next `Ref` when none exists yet.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "ShipmentController@show",
                "x-source": "app/Http/Controllers/ShipmentController.php#L127-L155",
                "x-route-name": "shipments.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Shipment"
                ],
                "parameters": [
                    {
                        "name": "shipment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`shipment` object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "shipment": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "shipment": {
                                        "Ref": "SH_1112",
                                        "sale_id": 41,
                                        "delivered_to": "Jane Doe",
                                        "shipping_address": "12 Main St",
                                        "status": "shipped",
                                        "shipping_details": "Tracking 1Z…"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_shipments_shipment",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Shipments"
                ],
                "summary": "Update a shipment",
                "description": "Mass-updates the shipment row with every field in the payload (`status`, `delivered_to`, `shipping_address`, `shipping_details`, `sale_id`) and sets the sale's `shipping_status`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "ShipmentController@update",
                "x-source": "app/Http/Controllers/ShipmentController.php#L159-L180",
                "x-route-name": "shipments.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "shipment",
                        "policy": "ShipmentPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Shipment",
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "shipment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shipment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale id (used to update the sale)."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New status. Required."
                                    },
                                    "delivered_to": {
                                        "type": "string",
                                        "description": "Recipient name.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "shipping_address": {
                                        "type": "string",
                                        "description": "Delivery address.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "shipping_details": {
                                        "type": "string",
                                        "description": "Carrier / tracking notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "status"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_shipments_shipment",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Shipments"
                ],
                "summary": "Update a shipment",
                "description": "Mass-updates the shipment row with every field in the payload (`status`, `delivered_to`, `shipping_address`, `shipping_details`, `sale_id`) and sets the sale's `shipping_status`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "ShipmentController@update",
                "x-source": "app/Http/Controllers/ShipmentController.php#L159-L180",
                "x-route-name": "shipments.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "shipment",
                        "policy": "ShipmentPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Shipment",
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "shipment",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Shipment id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "sale_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale id (used to update the sale)."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New status. Required."
                                    },
                                    "delivered_to": {
                                        "type": "string",
                                        "description": "Recipient name.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "shipping_address": {
                                        "type": "string",
                                        "description": "Delivery address.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "shipping_details": {
                                        "type": "string",
                                        "description": "Carrier / tracking notes.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "status"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/shopify/dashboard": {
            "get": {
                "operationId": "get_api_shopify_dashboard",
                "tags": [
                    "Shopify"
                ],
                "summary": "Shopify dashboard",
                "description": "Cross-store overview.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@dashboard",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L407-L488",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore",
                    "ShopifySyncRun",
                    "ShopifyLink",
                    "ShopifyLog"
                ],
                "responses": {
                    "200": {
                        "description": "Store counts, linked records, orders imported, run stats (30 d), errors (7 d), `by_entity[]`, `activity`, `stores[]`, `recent_runs[]`, `recent_errors[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "entity": {},
                                        "linked": {
                                            "type": "integer"
                                        },
                                        "runs": {
                                            "type": "integer"
                                        },
                                        "failed": {
                                            "type": "integer"
                                        },
                                        "stores_total": {
                                            "type": "integer"
                                        },
                                        "stores_connected": {
                                            "type": "integer"
                                        },
                                        "stores_error": {
                                            "type": "integer"
                                        },
                                        "linked_records": {
                                            "type": "integer"
                                        },
                                        "orders_imported": {
                                            "type": "integer"
                                        },
                                        "runs_30d": {
                                            "type": "integer"
                                        },
                                        "runs_failed_30d": {
                                            "type": "integer"
                                        },
                                        "errors_7d": {
                                            "type": "integer"
                                        },
                                        "running_now": {
                                            "type": "integer"
                                        },
                                        "by_entity": {},
                                        "activity": {},
                                        "stores": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recent_runs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recent_errors": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/logs": {
            "delete": {
                "operationId": "delete_api_shopify_logs",
                "tags": [
                    "Shopify"
                ],
                "summary": "Clear Shopify logs",
                "description": "Without `all=1` only logs older than 7 days are removed.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@clearLogs",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L386-L402",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "name": "all",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` to delete everything."
                    },
                    {
                        "name": "store_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Restrict to a store."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `deleted`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "deleted": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_shopify_logs",
                "tags": [
                    "Shopify"
                ],
                "summary": "Shopify logs",
                "description": "Paginated Shopify sync log entries (store, type, status, message).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@logs",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L342-L384",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "entity",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Entity."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "From."
                    },
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Level."
                    },
                    {
                        "name": "run_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Run."
                    },
                    {
                        "name": "store_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Store."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "To."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`logs[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "logs": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/mappings": {
            "get": {
                "operationId": "get_api_shopify_mappings",
                "tags": [
                    "Shopify"
                ],
                "summary": "List mappings",
                "description": "ERP record ↔ Shopify id links with the local record's name.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@mappings",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L200-L245",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ShopifyLink"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "entity_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`product`, `variant`, `inventory_item`, `customer`, `order`, `collection`."
                    },
                    {
                        "name": "store_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Store."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`mappings[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "mappings": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_shopify_mappings",
                "tags": [
                    "Shopify"
                ],
                "summary": "Link a record manually",
                "description": "Pair an ERP record with a Shopify id by hand.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@link",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L305-L338",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "shopify_sync | shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyLink"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entity_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "product",
                                            "variant",
                                            "inventory_item",
                                            "customer",
                                            "order",
                                            "collection"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:product,variant,inventory_item,customer,order,collection"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Entity type."
                                    },
                                    "local_id": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "ERP record id."
                                    },
                                    "shopify_id": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Shopify id."
                                    },
                                    "store_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "shopify_stores,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:shopify_stores,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Store."
                                    }
                                },
                                "required": [
                                    "entity_type",
                                    "local_id",
                                    "shopify_id",
                                    "store_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/mappings/{id}": {
            "delete": {
                "operationId": "delete_api_shopify_mappings_id",
                "tags": [
                    "Shopify"
                ],
                "summary": "Unlink a mapping",
                "description": "Local only: nothing is deleted in Shopify or the ERP.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@unlink",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L290-L302",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "shopify_sync | shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyLink",
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Mapping id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/meta": {
            "get": {
                "operationId": "get_api_shopify_meta",
                "tags": [
                    "Shopify"
                ],
                "summary": "Shopify lookups",
                "description": "Select options every Shopify page shares.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@meta",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L256-L284",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "ShopifyStore"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]`, `stores[]`, `entities[]`, `webhook_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stores": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "entities": {},
                                        "webhook_url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/stores": {
            "get": {
                "operationId": "get_api_shopify_stores",
                "tags": [
                    "Shopify"
                ],
                "summary": "List Shopify stores",
                "description": "Paginated; sortable `id, name, shop_domain, status, last_sync_at`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@index",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L27-L82",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ShopifyStore",
                    "ShopifyLink",
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`connected`, `error`, `disconnected`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`stores[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "stores": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_shopify_stores",
                "tags": [
                    "Shopify"
                ],
                "summary": "Connect a Shopify store",
                "description": "Verifies the Admin API token against the shop and saves the store as `connected` (or `error`).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@store",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L93-L134",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore",
                    "ShopifyLog"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "access_token": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Admin API access token."
                                    },
                                    "api_version": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Admin API version (default from config)."
                                    },
                                    "location_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shopify location id for inventory.",
                                        "type": "string"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Label."
                                    },
                                    "price_field": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "price",
                                            "wholesale_price",
                                            "min_price"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:price,wholesale_price,min_price"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Which price to push: `price`, `wholesale_price`, `min_price`."
                                    },
                                    "shop_domain": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`my-shop.myshopify.com`."
                                    },
                                    "sync_interval_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Scheduled sync interval.",
                                        "type": "integer"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse whose stock is synced."
                                    }
                                },
                                "required": [
                                    "access_token",
                                    "name",
                                    "shop_domain"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `store`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "store": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/stores/{id}": {
            "delete": {
                "operationId": "delete_api_shopify_stores_id",
                "tags": [
                    "Shopify"
                ],
                "summary": "Disconnect a Shopify store",
                "description": "Soft-deletes the store and drops its mappings.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@destroy",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L197-L213",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore",
                    "ShopifyLink",
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_shopify_stores_id",
                "tags": [
                    "Shopify"
                ],
                "summary": "Get a Shopify store",
                "description": "One connected Shopify store with its settings, mapping counts and last sync.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@show",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L84-L91",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`store` (token masked).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "store": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_shopify_stores_id",
                "tags": [
                    "Shopify"
                ],
                "summary": "Update a Shopify store",
                "description": "Leave `access_token` empty to keep the current one.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@update",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L136-L195",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "shopify_sync | shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore",
                    "ShopifyLink",
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "access_token": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New token."
                                    },
                                    "api_version": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "API version."
                                    },
                                    "location_id": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location.",
                                        "type": "string"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Label."
                                    },
                                    "price_field": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "price",
                                            "wholesale_price",
                                            "min_price"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:price,wholesale_price,min_price"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Price field."
                                    },
                                    "shop_domain": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Domain."
                                    },
                                    "sync_interval_minutes": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Interval.",
                                        "type": "integer"
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "warehouses,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "exists:warehouses,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse."
                                    },
                                    "webhook_secret": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Webhook HMAC secret."
                                    }
                                },
                                "required": [
                                    "name",
                                    "shop_domain"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `store`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "store": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/stores/{id}/locations": {
            "get": {
                "operationId": "get_api_shopify_stores_id_locations",
                "tags": [
                    "Shopify"
                ],
                "summary": "List Shopify locations",
                "description": "Shopify locations, so the user can pick which one holds this stock.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@locations",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L227-L253",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`locations[] {id, name, city, country}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "locations": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/stores/{id}/overview": {
            "get": {
                "operationId": "get_api_shopify_stores_id_overview",
                "tags": [
                    "Shopify"
                ],
                "summary": "Store overview",
                "description": "Everything the store detail page shows in one call.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@overview",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L370-L408",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore",
                    "ShopifyLink",
                    "ShopifySyncRun",
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`store`, `links` (count per entity), last 10 `runs`, last 10 `errors`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "store": {},
                                        "links": {
                                            "type": "object",
                                            "properties": {
                                                "product": {
                                                    "type": "integer"
                                                },
                                                "variant": {
                                                    "type": "integer"
                                                },
                                                "customer": {
                                                    "type": "integer"
                                                },
                                                "order": {
                                                    "type": "integer"
                                                },
                                                "collection": {
                                                    "type": "integer"
                                                },
                                                "inventory_item": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "runs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "errors": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/stores/{id}/test": {
            "post": {
                "operationId": "post_api_shopify_stores_id_test",
                "tags": [
                    "Shopify"
                ],
                "summary": "Test store credentials",
                "description": "Re-test the saved credentials and refresh the cached shop details.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyStoreController@testConnection",
                "x-source": "app/Http/Controllers/ShopifyStoreController.php#L216-L224",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and shop details.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Failed."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/sync/cancel/{id}": {
            "post": {
                "operationId": "post_api_shopify_sync_cancel_id",
                "tags": [
                    "Shopify"
                ],
                "summary": "Cancel a sync run",
                "description": "Requests cancellation; the worker stops between batches.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@cancel",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L119-L132",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "shopify_sync | shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifySyncRun",
                    "ShopifyLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Run id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `run`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "run": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Already finished.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "That run has already finished."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/sync/latest": {
            "get": {
                "operationId": "get_api_shopify_sync_latest",
                "tags": [
                    "Shopify"
                ],
                "summary": "Latest run per entity",
                "description": "The most recent run per entity for a store — powers the sync centre.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@latest",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L173-L189",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifySyncRun"
                ],
                "parameters": [
                    {
                        "name": "store_id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-exists": "shopify_stores,id",
                            "x-laravel-rules": [
                                "required",
                                "exists:shopify_stores,id"
                            ],
                            "x-sources": [
                                "validated",
                                "read"
                            ]
                        },
                        "description": "Store."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`latest` keyed by entity.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "latest": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/sync/runs": {
            "get": {
                "operationId": "get_api_shopify_sync_runs",
                "tags": [
                    "Shopify"
                ],
                "summary": "Sync run history",
                "description": "Run history, filterable by store and entity.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@runs",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L135-L170",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ShopifySyncRun"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`push` / `pull`."
                    },
                    {
                        "name": "entity",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Entity."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`queued`, `running`, `completed`, `failed`, `cancelled`."
                    },
                    {
                        "name": "store_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Store."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`runs[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "runs": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/sync/start": {
            "post": {
                "operationId": "post_api_shopify_sync_start",
                "tags": [
                    "Shopify"
                ],
                "summary": "Start a sync run",
                "description": "Creates a run and queues it. `orders` can only be pulled. Refused when the store is not connected, the entity is disabled for the store, or a run for that entity is already active (`409`).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@start",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L33-L103",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "shopify_sync | shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifyStore",
                    "ShopifySyncRun"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "direction": {
                                        "type": "string",
                                        "enum": [
                                            "push",
                                            "pull"
                                        ],
                                        "description": "Direction.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "dry_run": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Simulate without writing.",
                                        "type": "boolean"
                                    },
                                    "entity": {
                                        "type": "string",
                                        "enum": [
                                            "products",
                                            "inventory",
                                            "customers",
                                            "orders",
                                            "collections",
                                            "fulfillments"
                                        ],
                                        "description": "Entity.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "only_unsynced": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Skip already-mapped records.",
                                        "type": "boolean"
                                    },
                                    "since": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Only records updated after this date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "store_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "shopify_stores,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:shopify_stores,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Store."
                                    }
                                },
                                "required": [
                                    "store_id",
                                    "entity",
                                    "direction"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `run`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "run": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "409": {
                        "description": "A run is already active.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "run": {}
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/sync/status/{id}": {
            "get": {
                "operationId": "get_api_shopify_sync_status_id",
                "tags": [
                    "Shopify"
                ],
                "summary": "Sync run status",
                "description": "Progress for one run — the endpoint the UI polls.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifySyncController@status",
                "x-source": "app/Http/Controllers/ShopifySyncController.php#L106-L113",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "shopify_stores",
                        "policy": "ShopifyStorePolicy"
                    }
                ],
                "x-models": [
                    "ShopifySyncRun"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Run id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`run` (status, counters, progress, errors).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "run": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/webhook": {
            "post": {
                "operationId": "post_api_shopify_webhook",
                "tags": [
                    "Shopify"
                ],
                "summary": "Shopify webhook receiver",
                "description": "Public. Identified by `X-Shopify-Shop-Domain` / `X-Shopify-Topic`, verified with `X-Shopify-Hmac-Sha256` against the store's webhook secret, de-duplicated by `X-Shopify-Webhook-Id`. Unknown shops get `200` so Shopify stops retrying.",
                "x-section": "Integrations",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "ShopifyWebhookController@handle",
                "x-source": "app/Http/Controllers/ShopifyWebhookController.php#L41-L119",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "ShopifyStore",
                    "ShopifyLog",
                    "ShopifyWebhookEvent"
                ],
                "responses": {
                    "200": {
                        "description": "`ok` (may include `ignored`, `duplicate`, `stored`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "ignored": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "duplicate": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "stored": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Bad HMAC.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/api/shopify/webhook-events": {
            "get": {
                "operationId": "get_api_shopify_webhook_events",
                "tags": [
                    "Shopify"
                ],
                "summary": "Received webhook events",
                "description": "Stored webhook deliveries, for the UI.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyWebhookController@events",
                "x-source": "app/Http/Controllers/ShopifyWebhookController.php#L283-L314",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "ShopifyWebhookEvent"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `processed`, `failed`."
                    },
                    {
                        "name": "store_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Store."
                    },
                    {
                        "name": "topic",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Topic (e.g. `orders/create`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`events[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "events": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/shopify/webhook-events/{id}/replay": {
            "post": {
                "operationId": "post_api_shopify_webhook_events_id_replay",
                "tags": [
                    "Shopify"
                ],
                "summary": "Replay a webhook event",
                "description": "Re-run a webhook that failed, without asking Shopify to resend it.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "ShopifyWebhookController@replay",
                "x-source": "app/Http/Controllers/ShopifyWebhookController.php#L317-L338",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "ShopifyWebhookEvent",
                    "ShopifyStore"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Event id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Store gone / processing error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/show_product_data/{id}/{variant_id}": {
            "get": {
                "operationId": "get_api_show_product_data_id_variant_id",
                "tags": [
                    "Products"
                ],
                "summary": "Get product data for a document line",
                "description": "Returns one product (or one variant) in the shape used when adding a line to a sale, purchase, quotation, transfer, adjustment or damage: `id, code, name, image, product_type, Type_barcode, unit_id/unit, purchase_unit_id/unitPurchase, sale_unit_id/unitSale, tax_method, tax_percent, discount_method, discount, is_imei, not_selling, hide_from_online_store, is_batch_tracked`, prices converted to the sale/purchase unit (`Unit_price` = price in sale unit, `Net_price`/`Unit_cost` = cost in purchase unit, `wholesale_price`, `min_price`), `qte_sale` / `qte_purchase` (stock expressed in those units), `warehouse_location`, `packs[]` (multi-pack options) and `wholesale_tiers[]` (quantity price ladder).\n\nWithout a `warehouse_id` the stock figures are `0`. Only active products are returned (404 otherwise).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@show_product_data",
                "x-source": "app/Http/Controllers/ProductsController.php#L2188-L2523",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "product_warehouse",
                    "ProductWarehouseLocation",
                    "Setting",
                    "ProductPack"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    },
                    {
                        "name": "variant_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Variant id for `is_variant` products; send `null` for other types."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Line-item product data.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/show_product_data/{id}/{variant_id}/{warehouse_id}": {
            "get": {
                "operationId": "get_api_show_product_data_id_variant_id_warehouse_id",
                "tags": [
                    "Products"
                ],
                "summary": "Get product data for a document line (with warehouse stock)",
                "description": "Same as `GET /api/show_product_data/{id}/{variant_id}` but also fills `qte_sale` / `qte_purchase` with the stock held in `warehouse_id` and the product's shelf `warehouse_location` there. The warehouse must be assigned to the caller (403 otherwise).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@show_product_data",
                "x-source": "app/Http/Controllers/ProductsController.php#L2188-L2523",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "product_warehouse",
                    "ProductWarehouseLocation",
                    "Setting",
                    "ProductPack"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    },
                    {
                        "name": "variant_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Variant id, or `null`."
                    },
                    {
                        "name": "warehouse_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Warehouse whose stock should be reported."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Line-item product data with stock.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sidebar_menu_order": {
            "delete": {
                "operationId": "delete_api_sidebar_menu_order",
                "tags": [
                    "System Settings"
                ],
                "summary": "Reset sidebar menu order",
                "description": "Clears the custom order so the sidebar falls back to the built-in sequence.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@resetSidebarMenuOrder",
                "x-source": "app/Http/Controllers/SettingsController.php#L1075-L1087",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_sidebar_menu_order",
                "tags": [
                    "System Settings"
                ],
                "summary": "Get sidebar menu order",
                "description": "Returns the custom ordering of sidebar menu entries, or `null` when the default order is in use.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@getSidebarMenuOrder",
                "x-source": "app/Http/Controllers/SettingsController.php#L1051-L1057",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`{sidebar_menu_order: array|null}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sidebar_menu_order": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_sidebar_menu_order",
                "tags": [
                    "System Settings"
                ],
                "summary": "Save sidebar menu order",
                "description": "Stores the array of menu keys in the desired display order. Keys not present keep their default relative order after the listed ones.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@updateSidebarMenuOrder",
                "x-source": "app/Http/Controllers/SettingsController.php#L1059-L1073",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "order": {
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Array of menu item keys (e.g. `[\"dashboard\",\"sales\",\"products\"]`).",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "required": [
                                    "order"
                                ]
                            },
                            "example": {
                                "order": [
                                    "dashboard",
                                    "pos",
                                    "sales",
                                    "products",
                                    "reports"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Settings row missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Settings not found"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/size_guides": {
            "get": {
                "operationId": "get_api_size_guides",
                "tags": [
                    "Size Guides"
                ],
                "summary": "List size guides",
                "description": "Paginated size guides: `id, name, image, columns[], rows[], rows_count, status, created_at`. `search` matches the name.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SizeGuideController@index",
                "x-source": "app/Http/Controllers/SizeGuideController.php#L14-L54",
                "x-route-name": "size_guides.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "size_guides",
                        "policy": "SizeGuidePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SizeGuide"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`size_guides[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "image": {},
                                        "columns": {},
                                        "rows": {},
                                        "rows_count": {
                                            "type": "integer"
                                        },
                                        "status": {
                                            "type": "boolean"
                                        },
                                        "created_at": {
                                            "type": "string"
                                        },
                                        "size_guides": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "size_guides": [
                                        {
                                            "id": 1,
                                            "name": "Men's tops",
                                            "image": "12345678.png",
                                            "columns": [
                                                "Size",
                                                "Chest (cm)",
                                                "Waist (cm)"
                                            ],
                                            "rows": [
                                                [
                                                    "S",
                                                    "88-92",
                                                    "76-80"
                                                ],
                                                [
                                                    "M",
                                                    "96-100",
                                                    "84-88"
                                                ]
                                            ],
                                            "rows_count": 2,
                                            "status": true,
                                            "created_at": "2026-02-01 10:00:00"
                                        }
                                    ],
                                    "totalRows": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_size_guides",
                "tags": [
                    "Size Guides"
                ],
                "summary": "Create a size guide",
                "description": "Creates a guide. `columns` is an array of header labels and `rows` an array of arrays (one entry per column); both may be sent as JSON strings when using multipart. Returns HTTP **201**.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SizeGuideController@store",
                "x-source": "app/Http/Controllers/SizeGuideController.php#L57-L74",
                "x-route-name": "size_guides.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "size_guides",
                        "policy": "SizeGuidePolicy"
                    }
                ],
                "x-models": [
                    "SizeGuide"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "columns": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of column headers.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Optional chart image file."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Guide name."
                                    },
                                    "rows": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of rows, each an array of cell values matching `columns`.",
                                        "type": "array",
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    },
                                    "status": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`true` active (default) / `false` hidden.",
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Men's tops",
                                "columns": [
                                    "Size",
                                    "Chest (cm)"
                                ],
                                "rows": [
                                    [
                                        "S",
                                        "88-92"
                                    ],
                                    [
                                        "M",
                                        "96-100"
                                    ]
                                ],
                                "status": true
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/size_guides/delete/by_selection": {
            "post": {
                "operationId": "post_api_size_guides_delete_by_selection",
                "tags": [
                    "Size Guides"
                ],
                "summary": "Delete several size guides",
                "description": "Soft-deletes each id in `selectedIds`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SizeGuideController@delete_by_selection",
                "x-source": "app/Http/Controllers/SizeGuideController.php#L107-L116",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "size_guides",
                        "policy": "SizeGuidePolicy"
                    }
                ],
                "x-models": [
                    "SizeGuide"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of size guide ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/size_guides/list": {
            "get": {
                "operationId": "get_api_size_guides_list",
                "tags": [
                    "Size Guides"
                ],
                "summary": "List active size guides (picker)",
                "description": "Active guides as `{id, name}` ordered by name for the product form dropdown.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SizeGuideController@list",
                "x-source": "app/Http/Controllers/SizeGuideController.php#L121-L129",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "size_guides",
                        "policy": "SizeGuidePolicy"
                    }
                ],
                "x-models": [
                    "SizeGuide"
                ],
                "responses": {
                    "200": {
                        "description": "`size_guides[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "size_guides": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/size_guides/{size_guide}": {
            "delete": {
                "operationId": "delete_api_size_guides_size_guide",
                "tags": [
                    "Size Guides"
                ],
                "summary": "Delete a size guide",
                "description": "Soft-deletes the guide.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SizeGuideController@destroy",
                "x-source": "app/Http/Controllers/SizeGuideController.php#L98-L105",
                "x-route-name": "size_guides.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "size_guides",
                        "policy": "SizeGuidePolicy"
                    }
                ],
                "x-models": [
                    "SizeGuide"
                ],
                "parameters": [
                    {
                        "name": "size_guide",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Size guide id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_size_guides_size_guide",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Size Guides"
                ],
                "summary": "Update a size guide",
                "description": "Replaces name, columns, rows and status; a new `image` replaces the previous one.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SizeGuideController@update",
                "x-source": "app/Http/Controllers/SizeGuideController.php#L77-L95",
                "x-route-name": "size_guides.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "size_guides",
                        "policy": "SizeGuidePolicy"
                    }
                ],
                "x-models": [
                    "SizeGuide"
                ],
                "parameters": [
                    {
                        "name": "size_guide",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Size guide id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "columns": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Column headers.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "New image file."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Guide name."
                                    },
                                    "rows": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows.",
                                        "type": "array",
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    },
                                    "status": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag.",
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_size_guides_size_guide",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Size Guides"
                ],
                "summary": "Update a size guide",
                "description": "Replaces name, columns, rows and status; a new `image` replaces the previous one.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SizeGuideController@update",
                "x-source": "app/Http/Controllers/SizeGuideController.php#L77-L95",
                "x-route-name": "size_guides.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "size_guides",
                        "policy": "SizeGuidePolicy"
                    }
                ],
                "x-models": [
                    "SizeGuide"
                ],
                "parameters": [
                    {
                        "name": "size_guide",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Size guide id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "columns": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Column headers.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "New image file."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Guide name."
                                    },
                                    "rows": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows.",
                                        "type": "array",
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    },
                                    "status": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Active flag.",
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/slack/settings": {
            "get": {
                "operationId": "get_api_slack_settings",
                "tags": [
                    "Slack"
                ],
                "summary": "Get Slack settings",
                "description": "Slack integration settings: webhook URL (masked), channel, enabled events.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SlackSettingsController@show",
                "x-source": "app/Http/Controllers/Integrations/SlackSettingsController.php#L19-L32",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "SlackSettingPolicy"
                    }
                ],
                "x-models": [
                    "SlackSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `configured`, `webhook_hint`, `events[]`, `available_events[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "configured": {},
                                        "webhook_hint": {
                                            "type": "string"
                                        },
                                        "events": {},
                                        "available_events": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_slack_settings",
                "tags": [
                    "Slack"
                ],
                "summary": "Save Slack settings",
                "description": "`webhook_url` is write-only: send it only to replace it.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SlackSettingsController@update",
                "x-source": "app/Http/Controllers/Integrations/SlackSettingsController.php#L34-L61",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SlackSettingPolicy"
                    }
                ],
                "x-models": [
                    "SlackSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "events": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Events to forward.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "webhook_url": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-rules": [
                                            "starts_with:https://hooks.slack.com/"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500",
                                            "starts_with:https://hooks.slack.com/"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Slack incoming webhook URL."
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `configured`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "configured": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/slack/settings/test": {
            "post": {
                "operationId": "post_api_slack_settings_test",
                "tags": [
                    "Slack"
                ],
                "summary": "Send a Slack test message",
                "description": "Posts a test message to the configured Slack webhook and reports the result.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\SlackSettingsController@test",
                "x-source": "app/Http/Controllers/Integrations/SlackSettingsController.php#L63-L77",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "SlackSettingPolicy"
                    }
                ],
                "x-models": [
                    "SlackSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {},
                                        "error": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not configured or send failed (`error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Add a webhook URL first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/banners": {
            "get": {
                "operationId": "get_api_store_banners",
                "tags": [
                    "Store Banners"
                ],
                "summary": "List banners",
                "description": "Paginated storefront banners with image, position, link, schedule and active flag.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\BannersApiController@index",
                "x-source": "app/Http/Controllers/Api/Store/BannersApiController.php#L13-L39",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Banners_view",
                        "policy": "StoreBannerPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "StoreBanner"
                ],
                "parameters": [
                    {
                        "name": "dir",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`asc` / `desc`."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Column (default `updated_at`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[] {id, title, position, active, updated_at, image, image_url}` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "title": {},
                                        "position": {},
                                        "active": {},
                                        "updated_at": {
                                            "type": "string"
                                        },
                                        "image": {},
                                        "image_url": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "integer"
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_banners",
                "tags": [
                    "Store Banners"
                ],
                "summary": "Create a banner",
                "description": "Creates a banner (multipart image, title, subtitle, link, position, sort order, start/end dates, active flag).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\BannersApiController@store",
                "x-source": "app/Http/Controllers/Api/Store/BannersApiController.php#L41-L82",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Banners_view",
                        "policy": "StoreBannerPolicy"
                    }
                ],
                "x-models": [
                    "StoreBanner"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp,gif",
                                        "maxLength": 4096,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp,gif",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Image (jpg/png/webp/gif, max 4 MB)."
                                    },
                                    "position": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Placement key (e.g. `hero`, `sidebar`)."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "201": {
                        "description": "The banner.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/banners/{id}": {
            "delete": {
                "operationId": "delete_api_store_banners_id",
                "tags": [
                    "Store Banners"
                ],
                "summary": "Delete a banner",
                "description": "Deletes a banner and its image.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\BannersApiController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/BannersApiController.php#L145-L163",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Banners_view",
                        "policy": "StoreBannerPolicy"
                    }
                ],
                "x-models": [
                    "StoreBanner"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Banner id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_store_banners_id",
                "tags": [
                    "Store Banners"
                ],
                "summary": "Get a banner",
                "description": "One banner.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\BannersApiController@show",
                "x-source": "app/Http/Controllers/Api/Store/BannersApiController.php#L84-L92",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Banners_view",
                        "policy": "StoreBannerPolicy"
                    }
                ],
                "x-models": [
                    "StoreBanner"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Banner id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Banner with `image_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_banners_id",
                "tags": [
                    "Store Banners"
                ],
                "summary": "Update a banner",
                "description": "Updates a banner; send as multipart to replace the image.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\BannersApiController@update",
                "x-source": "app/Http/Controllers/Api/Store/BannersApiController.php#L94-L143",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Banners_view",
                        "policy": "StoreBannerPolicy"
                    }
                ],
                "x-models": [
                    "StoreBanner"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Banner id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp,gif",
                                        "maxLength": 4096,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp,gif",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "New image."
                                    },
                                    "link": {
                                        "type": "string",
                                        "format": "uri",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "url"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Target URL."
                                    },
                                    "position": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Placement."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "The banner.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/bkash/return": {
            "get": {
                "operationId": "get_api_store_bkash_return",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "bKash return URL",
                "description": "Executes the payment server-side (with query fallback) on `success`; `cancel` / `failure` cancel the order.",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@bkashReturn",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L955-L1019",
                "x-route-name": "store.bkash.return",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "paymentID",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "bKash payment id."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`success`, `failure` or `cancel`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/api/store/coupons": {
            "get": {
                "operationId": "get_api_store_coupons",
                "tags": [
                    "Store Coupons"
                ],
                "summary": "List coupons",
                "description": "All coupons with `redemptions_count`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StoreCouponsController@index",
                "x-source": "app/Http/Controllers/Api/Store/StoreCouponsController.php#L13-L26",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreCoupon"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`coupons[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "coupons": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_coupons",
                "tags": [
                    "Store Coupons"
                ],
                "summary": "Create a coupon",
                "description": "Creates a coupon: code, type (percentage/fixed/free shipping), value, minimum order, usage limits, validity dates, active flag.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StoreCouponsController@store",
                "x-source": "app/Http/Controllers/Api/Store/StoreCouponsController.php#L28-L36",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreCoupon"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "x-unique": "store_coupons,code ->ignore->whereNull",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:60",
                                            "unique:store_coupons,code ->ignore->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unique code."
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Enabled flag.",
                                        "type": "boolean"
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Valid to."
                                    },
                                    "max_discount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Cap for percentage coupons."
                                    },
                                    "min_order_amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Minimum cart subtotal."
                                    },
                                    "per_customer_limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Redemptions per customer."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Valid from."
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "description": "Discount type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "usage_limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Total redemptions allowed."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Discount value."
                                    }
                                },
                                "required": [
                                    "code",
                                    "type",
                                    "value",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/coupons/{id}": {
            "delete": {
                "operationId": "delete_api_store_coupons_id",
                "tags": [
                    "Store Coupons"
                ],
                "summary": "Delete a coupon",
                "description": "Deletes a coupon; orders that used it keep the discount.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StoreCouponsController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/StoreCouponsController.php#L48-L55",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreCoupon"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Coupon id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_coupons_id",
                "tags": [
                    "Store Coupons"
                ],
                "summary": "Update a coupon",
                "description": "Updates a coupon with the same fields as creation.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StoreCouponsController@update",
                "x-source": "app/Http/Controllers/Api/Store/StoreCouponsController.php#L38-L46",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreCoupon"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Coupon id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "x-unique": "store_coupons,code ->ignore->whereNull",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:60",
                                            "unique:store_coupons,code ->ignore->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Code."
                                    },
                                    "description": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "enabled": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Enabled.",
                                        "type": "boolean"
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "To."
                                    },
                                    "max_discount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Cap."
                                    },
                                    "min_order_amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Min subtotal."
                                    },
                                    "per_customer_limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per customer."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "From."
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "percentage",
                                            "fixed"
                                        ],
                                        "description": "Discount type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "usage_limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Usage limit."
                                    },
                                    "value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Value."
                                    }
                                },
                                "required": [
                                    "code",
                                    "type",
                                    "value",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/flash-sales": {
            "get": {
                "operationId": "get_api_store_flash_sales",
                "tags": [
                    "Flash Sales"
                ],
                "summary": "List flash sales",
                "description": "All sales with `products_count` and `is_running`, plus store `locales`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\FlashSalesController@index",
                "x-source": "app/Http/Controllers/Api/Store/FlashSalesController.php#L14-L40",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "FlashSale"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`flash_sales[]` and `locales`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "flash_sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "locales": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_flash_sales",
                "tags": [
                    "Flash Sales"
                ],
                "summary": "Create a flash sale",
                "description": "Creates a flash sale: name, start/end, and the products with their discount type and value. Storefront prices switch automatically while it is active.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\FlashSalesController@store",
                "x-source": "app/Http/Controllers/Api/Store/FlashSalesController.php#L69-L90",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "FlashSale"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ends_at": {
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "End date-time (>= start).",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active (default true)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "name_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-locale names `{locale: name}`.",
                                        "type": "object"
                                    },
                                    "products": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "discount_type": {
                                                    "x-inferred": true,
                                                    "type": "string",
                                                    "enum": [
                                                        "percent",
                                                        "fixed"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "in:percent,fixed"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`percent` or `fixed`."
                                                },
                                                "discount_value": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Discount value."
                                                },
                                                "product_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product."
                                                }
                                            },
                                            "required": [
                                                "discount_type",
                                                "discount_value",
                                                "product_id"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Discounted products."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Display order."
                                    },
                                    "starts_at": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Start date-time.",
                                        "type": "string",
                                        "format": "date-time"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Weekend deals",
                                "is_active": true,
                                "starts_at": "2026-09-12 00:00:00",
                                "ends_at": "2026-09-13 23:59:59",
                                "products": [
                                    {
                                        "product_id": 120,
                                        "discount_type": "percent",
                                        "discount_value": 20
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/flash-sales/search-products": {
            "get": {
                "operationId": "get_api_store_flash_sales_search_products",
                "tags": [
                    "Flash Sales"
                ],
                "summary": "Product typeahead for the builder",
                "description": "Product typeahead for the admin builder.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\FlashSalesController@searchProducts",
                "x-source": "app/Http/Controllers/Api/Store/FlashSalesController.php#L124-L138",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name or code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`products[] {id, name, code, price}` (max 20).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/flash-sales/{id}": {
            "delete": {
                "operationId": "delete_api_store_flash_sales_id",
                "tags": [
                    "Flash Sales"
                ],
                "summary": "Delete a flash sale",
                "description": "Deletes a flash sale and restores normal prices.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\FlashSalesController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/FlashSalesController.php#L114-L121",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "FlashSale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Flash sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_store_flash_sales_id",
                "tags": [
                    "Flash Sales"
                ],
                "summary": "Get a flash sale",
                "description": "Sale with its `products[] {product_id, name, code, price, discount_type, discount_value, flash_price}`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\FlashSalesController@show",
                "x-source": "app/Http/Controllers/Api/Store/FlashSalesController.php#L42-L67",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "FlashSale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Flash sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Flash sale object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "name_translations": {},
                                        "locales": {},
                                        "is_active": {
                                            "type": "boolean"
                                        },
                                        "starts_at": {
                                            "type": "string"
                                        },
                                        "ends_at": {
                                            "type": "string"
                                        },
                                        "sort_order": {
                                            "type": "integer"
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_flash_sales_id",
                "tags": [
                    "Flash Sales"
                ],
                "summary": "Update a flash sale",
                "description": "`products` replaces the whole list.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\FlashSalesController@update",
                "x-source": "app/Http/Controllers/Api/Store/FlashSalesController.php#L92-L112",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "FlashSale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Flash sale id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ends_at": {
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "End.",
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "name_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Translations.",
                                        "type": "object"
                                    },
                                    "products": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "discount_type": {
                                                    "x-inferred": true,
                                                    "type": "string",
                                                    "enum": [
                                                        "percent",
                                                        "fixed"
                                                    ],
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "in:percent,fixed"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "`percent` or `fixed`."
                                                },
                                                "discount_value": {
                                                    "type": "number",
                                                    "minimum": 0,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "numeric",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Discount value."
                                                },
                                                "product_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product."
                                                }
                                            },
                                            "required": [
                                                "discount_type",
                                                "discount_value",
                                                "product_id"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Products (full replacement)."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    },
                                    "starts_at": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Start.",
                                        "type": "string",
                                        "format": "date-time"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Weekend deals",
                                "is_active": true,
                                "starts_at": "2026-09-12 00:00:00",
                                "ends_at": "2026-09-13 23:59:59",
                                "products": [
                                    {
                                        "product_id": 120,
                                        "discount_type": "percent",
                                        "discount_value": 20
                                    }
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/gift-cards": {
            "get": {
                "operationId": "get_api_store_gift_cards",
                "tags": [
                    "Gift Cards"
                ],
                "summary": "List gift cards",
                "description": "Paginated gift cards with code, initial and remaining balance, buyer, recipient, expiry and status.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\GiftCardController@index",
                "x-source": "app/Http/Controllers/Api/Store/GiftCardController.php#L20-L47",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "GiftCardPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "GiftCard"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`active`, `redeemed`, `disabled`, `expired`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_gift_cards",
                "tags": [
                    "Gift Cards"
                ],
                "summary": "Create gift cards",
                "description": "Set `quantity` > 1 to generate a batch of identical cards with generated codes (max 500). `balance` starts equal to `amount`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\GiftCardController@store",
                "x-source": "app/Http/Controllers/Api/Store/GiftCardController.php#L49-L83",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "GiftCardPolicy"
                    }
                ],
                "x-models": [
                    "GiftCard"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Face value."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-unique": "gift_cards,code ->ignore",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60",
                                            "unique:gift_cards,code ->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Custom code (single card only; generated when empty)."
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Expiry."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label."
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Internal note."
                                    },
                                    "quantity": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Number of cards to generate (default 1)."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "disabled"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:active,disabled"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`active` (default) or `disabled`."
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "gift_card",
                                            "voucher",
                                            "store_credit"
                                        ],
                                        "description": "Card type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "amount",
                                    "type",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success`, `count`, `cards[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "cards": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/gift-cards/{id}": {
            "delete": {
                "operationId": "delete_api_store_gift_cards_id",
                "tags": [
                    "Gift Cards"
                ],
                "summary": "Delete a gift card",
                "description": "Deletes an unused gift card.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\GiftCardController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/GiftCardController.php#L119-L126",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "GiftCardPolicy"
                    }
                ],
                "x-models": [
                    "GiftCard"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Card id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_gift_cards_id",
                "tags": [
                    "Gift Cards"
                ],
                "summary": "Update a gift card",
                "description": "A redeemed card only accepts `name` and `note`. For unredeemed cards the balance follows the new `amount`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\GiftCardController@update",
                "x-source": "app/Http/Controllers/Api/Store/GiftCardController.php#L85-L117",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "GiftCardPolicy"
                    }
                ],
                "x-models": [
                    "GiftCard"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Card id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Face value."
                                    },
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-unique": "gift_cards,code ->ignore",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60",
                                            "unique:gift_cards,code ->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Code."
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Expiry."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label."
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Note."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "disabled"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:active,disabled"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`active` or `disabled`."
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "gift_card",
                                            "voucher",
                                            "store_credit"
                                        ],
                                        "description": "Card type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "amount",
                                    "type",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/invite-codes": {
            "get": {
                "operationId": "get_api_store_invite_codes",
                "tags": [
                    "Invite Codes"
                ],
                "summary": "List invite codes",
                "description": "Paginated invite codes with usage count, limit, expiry and status (used when registration requires an invite code).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\InviteCodesController@index",
                "x-source": "app/Http/Controllers/Api/Store/InviteCodesController.php#L13-L42",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "InviteCode"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`active` (usable) or `inactive` (disabled, expired or exhausted)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_invite_codes",
                "tags": [
                    "Invite Codes"
                ],
                "summary": "Create an invite code",
                "description": "`code` is generated (8 uppercase chars) when omitted.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\InviteCodesController@store",
                "x-source": "app/Http/Controllers/Api/Store/InviteCodesController.php#L44-L65",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "InviteCode"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-unique": "invite_codes,code",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64",
                                            "unique:invite_codes,code"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Custom code (unique)."
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after:now"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after:now"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Expiry (future)."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active (default true)."
                                    },
                                    "max_uses": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Maximum redemptions."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "201": {
                        "description": "The invite code.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/invite-codes/batch": {
            "post": {
                "operationId": "post_api_store_invite_codes_batch",
                "tags": [
                    "Invite Codes"
                ],
                "summary": "Generate invite codes in batch",
                "description": "Generates `count` random invite codes at once with a shared usage limit and expiry.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\InviteCodesController@generateBatch",
                "x-source": "app/Http/Controllers/Api/Store/InviteCodesController.php#L103-L127",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "InviteCode"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "count": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 50,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:1",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Number of codes (1–50)."
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after:now"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after:now"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Expiry."
                                    },
                                    "max_uses": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Max uses per code."
                                    }
                                },
                                "required": [
                                    "count"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`generated` and `codes[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "generated": {
                                            "type": "integer"
                                        },
                                        "codes": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/invite-codes/{id}": {
            "delete": {
                "operationId": "delete_api_store_invite_codes_id",
                "tags": [
                    "Invite Codes"
                ],
                "summary": "Delete an invite code",
                "description": "Deletes an invite code.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\InviteCodesController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/InviteCodesController.php#L93-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "InviteCode"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Code id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_store_invite_codes_id",
                "tags": [
                    "Invite Codes"
                ],
                "summary": "Get an invite code",
                "description": "With `registrations_count`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\InviteCodesController@show",
                "x-source": "app/Http/Controllers/Api/Store/InviteCodesController.php#L67-L74",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "InviteCode"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Code id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Invite code.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_invite_codes_id",
                "tags": [
                    "Invite Codes"
                ],
                "summary": "Update an invite code",
                "description": "Updates an invite code's limit, expiry or active flag.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\InviteCodesController@update",
                "x-source": "app/Http/Controllers/Api/Store/InviteCodesController.php#L76-L91",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "InviteCode"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Code id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Expiry."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "max_uses": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Max uses."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "The invite code.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/messages": {
            "get": {
                "operationId": "get_api_store_messages",
                "tags": [
                    "Contact Messages"
                ],
                "summary": "List contact messages",
                "description": "Paginated messages sent from the storefront contact form with read flag.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\MessageController@index",
                "x-source": "app/Http/Controllers/Api/Store/MessageController.php#L33-L88",
                "x-route-name": "messages.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Messages_view",
                        "policy": "MessagePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Message"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "name": "dir",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Direction."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 20)."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name, email, subject or body."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Column."
                    },
                    {
                        "name": "unread",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = unread only."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[] {id, name, email, subject, is_read, created_at}` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "email": {},
                                        "subject": {},
                                        "is_read": {
                                            "type": "boolean"
                                        },
                                        "created_at": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "integer"
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "per_page": {
                                                    "type": "integer"
                                                },
                                                "current": {
                                                    "type": "integer"
                                                },
                                                "last_page": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/messages/{id}": {
            "delete": {
                "operationId": "delete_api_store_messages_id",
                "tags": [
                    "Contact Messages"
                ],
                "summary": "Delete a contact message",
                "description": "Deletes a contact message.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\MessageController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/MessageController.php#L126-L132",
                "x-route-name": "messages.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Messages_view",
                        "policy": "MessagePolicy"
                    }
                ],
                "x-models": [
                    "Message"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Message id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_store_messages_id",
                "tags": [
                    "Contact Messages"
                ],
                "summary": "Get a contact message",
                "description": "Marks it read.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\MessageController@show",
                "x-source": "app/Http/Controllers/Api/Store/MessageController.php#L91-L112",
                "x-route-name": "messages.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Messages_view",
                        "policy": "MessagePolicy"
                    }
                ],
                "x-models": [
                    "Message"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Message id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Message object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "email": {},
                                        "phone": {},
                                        "subject": {},
                                        "message": {},
                                        "is_read": {
                                            "type": "boolean"
                                        },
                                        "created_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/messages/{id}/toggle-read": {
            "patch": {
                "operationId": "patch_api_store_messages_id_toggle_read",
                "tags": [
                    "Contact Messages"
                ],
                "summary": "Toggle read flag",
                "description": "Flips the read/unread flag of a message.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\MessageController@toggleRead",
                "x-source": "app/Http/Controllers/Api/Store/MessageController.php#L115-L124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Messages_view",
                        "policy": "MessagePolicy"
                    }
                ],
                "x-models": [
                    "Message"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Message id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `is_read`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "is_read": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/orders": {
            "get": {
                "operationId": "get_api_store_orders",
                "tags": [
                    "Online Orders"
                ],
                "summary": "List online orders",
                "description": "Laravel-style page of orders (`data[]`, `meta`), newest first. Each row: `id, code (ref), customer_name, status, has_preorder_items, total, payment_method, payment_status, delivery_method, has_pending_proof, is_flagged, flag_reason, created_at`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\OnlineOrdersApiController@index",
                "x-source": "app/Http/Controllers/Api/Store/OnlineOrdersApiController.php#L47-L116",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "OnlineOrder"
                ],
                "parameters": [
                    {
                        "name": "dir",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`asc` or `desc`."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Order date from."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (1–200, default 10)."
                    },
                    {
                        "name": "preorder",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`1` = only orders containing pre-order lines."
                    },
                    {
                        "name": "proof",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending` = only orders with a payment proof awaiting review."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search on ref or customer name / email."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`date`, `created_at`, `total`, `ref`, `id`."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `confirmed`, `shipped`, `delivered`, `cancelled`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Order date to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "code": {},
                                        "customer_name": {},
                                        "status": {},
                                        "has_preorder_items": {
                                            "type": "boolean"
                                        },
                                        "total": {
                                            "type": "number"
                                        },
                                        "payment_method": {},
                                        "payment_status": {},
                                        "delivery_method": {},
                                        "has_pending_proof": {},
                                        "is_flagged": {
                                            "type": "boolean"
                                        },
                                        "flag_reason": {},
                                        "created_at": {},
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/orders/{id}": {
            "get": {
                "operationId": "get_api_store_orders_id",
                "tags": [
                    "Online Orders"
                ],
                "summary": "Get an online order",
                "description": "Header (customer, shipping address, warehouse, totals, payment / delivery info, pickup branch, `payment_proofs[]`) and `items[]` (`product_id, product_variant_id, name, qty, price, line_total, is_preorder`).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\OnlineOrdersApiController@show",
                "x-source": "app/Http/Controllers/Api/Store/OnlineOrdersApiController.php#L122-L202",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Order object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "code": {},
                                        "status": {},
                                        "has_preorder_items": {
                                            "type": "boolean"
                                        },
                                        "shipping_status": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "customer_name": {},
                                        "customer_email": {},
                                        "customer_phone": {},
                                        "customer_address": {},
                                        "shipping_city": {},
                                        "shipping_state": {},
                                        "shipping_zip": {},
                                        "shipping_country": {},
                                        "warehouse_id": {},
                                        "warehouse_name": {},
                                        "subtotal": {
                                            "type": "integer"
                                        },
                                        "tax": {
                                            "type": "number"
                                        },
                                        "tax_rate": {
                                            "type": "number"
                                        },
                                        "shipping": {
                                            "type": "number"
                                        },
                                        "shipping_method_name": {},
                                        "discount": {
                                            "type": "number",
                                            "example": 0
                                        },
                                        "total": {
                                            "type": "number"
                                        },
                                        "is_flagged": {
                                            "type": "boolean"
                                        },
                                        "flag_reason": {},
                                        "payment_method": {},
                                        "payment_status": {},
                                        "delivery_method": {},
                                        "pickup_branch_id": {},
                                        "pickup_branch_name": {},
                                        "payment_proofs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "product_id": {},
                                        "product_variant_id": {},
                                        "name": {
                                            "type": "string"
                                        },
                                        "qty": {
                                            "type": "number"
                                        },
                                        "price": {
                                            "type": "number"
                                        },
                                        "line_total": {
                                            "type": "number"
                                        },
                                        "is_preorder": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_store_orders_id",
                "tags": [
                    "Online Orders"
                ],
                "summary": "Change order status",
                "description": "Applies a lifecycle transition (`pending→confirmed|cancelled`, `confirmed→shipped`, `shipped→delivered`). **Confirming** creates the Sale (with payment if the order is paid) in `warehouse_id`, deducts stock and returns `sale_id` / `sale_ref`. Invalid transitions return `422`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\OnlineOrdersApiController@update",
                "x-source": "app/Http/Controllers/Api/Store/OnlineOrdersApiController.php#L285-L559",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "OnlineOrder",
                    "Warehouse",
                    "Product",
                    "product_warehouse",
                    "Sale",
                    "SaleDetail",
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "confirmed",
                                            "shipped",
                                            "delivered",
                                            "cancelled"
                                        ],
                                        "description": "Target status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse to book the sale under (confirm only)."
                                    }
                                },
                                "required": [
                                    "status",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `status`, and for confirm `sale_id`, `sale_ref`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {
                                            "type": "string",
                                            "example": "confirmed"
                                        },
                                        "sale_id": {},
                                        "sale_ref": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/orders/{id}/confirm-options": {
            "get": {
                "operationId": "get_api_store_orders_id_confirm_options",
                "tags": [
                    "Online Orders"
                ],
                "summary": "Warehouses available to confirm the order",
                "description": "For the confirm dialog: every warehouse the admin may book the sale under, with `can_fulfil` and per-line `shortages` for this order (pre-order lines excluded). Store-enabled warehouses come first.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\OnlineOrdersApiController@confirmOptions",
                "x-source": "app/Http/Controllers/Api/Store/OnlineOrdersApiController.php#L210-L283",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "OnlineOrder",
                    "StoreSetting",
                    "Warehouse",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`order_warehouse_id` and `warehouses[] {id, name, store_enabled, can_fulfil, shortages[]}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "integer"
                                        },
                                        "name": {},
                                        "store_enabled": {},
                                        "can_fulfil": {},
                                        "shortages": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "order_warehouse_id": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/orders/{id}/invoice": {
            "get": {
                "operationId": "get_api_store_orders_id_invoice",
                "tags": [
                    "Online Orders"
                ],
                "summary": "Download the order invoice (PDF)",
                "description": "GET /store/orders/{id}/invoice — admin downloads an order invoice. /",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\OnlineOrdersApiController@invoice",
                "x-source": "app/Http/Controllers/Api/Store/OnlineOrdersApiController.php#L27-L40",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/orders/{id}/payment-proofs/{proofId}/review": {
            "post": {
                "operationId": "post_api_store_orders_id_payment_proofs_proofId_review",
                "tags": [
                    "Online Orders"
                ],
                "summary": "Review a payment proof",
                "description": "Approve or reject a shopper-submitted GCash / bank-transfer proof. Approval marks the order paid (so a later confirm records the payment on the Sale).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\OnlineOrdersApiController@reviewProof",
                "x-source": "app/Http/Controllers/Api/Store/OnlineOrdersApiController.php#L606-L650",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    },
                    {
                        "name": "proofId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Proof id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reject_reason": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reason shown to the customer when rejecting."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "approved",
                                            "rejected"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:approved,rejected"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`approved` or `rejected`."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, proof `status`, order `payment_status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {},
                                        "payment_status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/pages": {
            "get": {
                "operationId": "get_api_store_pages",
                "tags": [
                    "Store Pages"
                ],
                "summary": "List pages",
                "description": "Paginated CMS pages (About, Terms, …) with slug, status and last update.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PagesApiController@index",
                "x-source": "app/Http/Controllers/Api/Store/PagesApiController.php#L12-L30",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-paginated": true,
                "x-models": [
                    "StorePage"
                ],
                "parameters": [
                    {
                        "name": "dir",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Direction."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Title or slug."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Column."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]`, `meta`, `locales`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "locales": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_pages",
                "tags": [
                    "Store Pages"
                ],
                "summary": "Create a page",
                "description": "`slug` is generated from the title when omitted. Translation maps are keyed by locale.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PagesApiController@store",
                "x-source": "app/Http/Controllers/Api/Store/PagesApiController.php#L32-L60",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "StorePage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "content": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "HTML content."
                                    },
                                    "content_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`{locale: html}`.",
                                        "type": "object"
                                    },
                                    "published": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Visible on the storefront."
                                    },
                                    "seo_description": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO description."
                                    },
                                    "seo_description_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`{locale: text}`.",
                                        "type": "object"
                                    },
                                    "seo_title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO title."
                                    },
                                    "seo_title_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`{locale: text}`.",
                                        "type": "object"
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-unique": "store_pages,slug",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190",
                                            "unique:store_pages,slug"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Unique slug."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    },
                                    "title_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`{locale: title}`.",
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The page.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/pages/{id}": {
            "delete": {
                "operationId": "delete_api_store_pages_id",
                "tags": [
                    "Store Pages"
                ],
                "summary": "Delete a page",
                "description": "Deletes a page.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PagesApiController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/PagesApiController.php#L100-L106",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "StorePage"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_store_pages_id",
                "tags": [
                    "Store Pages"
                ],
                "summary": "Get a page",
                "description": "One page with its HTML content and translations.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PagesApiController@show",
                "x-source": "app/Http/Controllers/Api/Store/PagesApiController.php#L62-L67",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "StorePage"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Page object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_pages_id",
                "tags": [
                    "Store Pages"
                ],
                "summary": "Update a page",
                "description": "Updates a page's title, slug, content, translations, SEO fields and published flag.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PagesApiController@update",
                "x-source": "app/Http/Controllers/Api/Store/PagesApiController.php#L69-L98",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "StorePage"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "content": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Content."
                                    },
                                    "content_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Translations.",
                                        "type": "object"
                                    },
                                    "published": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Published."
                                    },
                                    "seo_description": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO description."
                                    },
                                    "seo_description_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Translations.",
                                        "type": "object"
                                    },
                                    "seo_title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "SEO title."
                                    },
                                    "seo_title_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Translations.",
                                        "type": "object"
                                    },
                                    "slug": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-unique": "store_pages,slug ->ignore",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190",
                                            "unique:store_pages,slug ->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Slug."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    },
                                    "title_translations": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Translations.",
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The page.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/pending-customers": {
            "get": {
                "operationId": "get_api_store_pending_customers",
                "tags": [
                    "Pending Customers"
                ],
                "summary": "List pending registrations",
                "description": "Laravel paginator of e-commerce accounts with `status = 0`, with client and invite code.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PendingCustomersController@index",
                "x-source": "app/Http/Controllers/Api/Store/PendingCustomersController.php#L16-L39",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "EcommerceClient"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 15)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/pending-customers/approve-all": {
            "post": {
                "operationId": "post_api_store_pending_customers_approve_all",
                "tags": [
                    "Pending Customers"
                ],
                "summary": "Approve all pending registrations",
                "description": "Approves every pending storefront registration in one go and sends the welcome emails.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PendingCustomersController@approveAll",
                "x-source": "app/Http/Controllers/Api/Store/PendingCustomersController.php#L74-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient"
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `approved_count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "approved_count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/pending-customers/{id}/approve": {
            "post": {
                "operationId": "post_api_store_pending_customers_id_approve",
                "tags": [
                    "Pending Customers"
                ],
                "summary": "Approve a registration",
                "description": "Activates the account and emails the customer.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PendingCustomersController@approve",
                "x-source": "app/Http/Controllers/Api/Store/PendingCustomersController.php#L41-L56",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "E-commerce client id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success`, `message`, `customer`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Customer approved successfully."
                                        },
                                        "customer": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/pending-customers/{id}/reject": {
            "post": {
                "operationId": "post_api_store_pending_customers_id_reject",
                "tags": [
                    "Pending Customers"
                ],
                "summary": "Reject a registration",
                "description": "Deletes the account and emails the customer.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PendingCustomersController@reject",
                "x-source": "app/Http/Controllers/Api/Store/PendingCustomersController.php#L58-L72",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "EcommerceClient"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "E-commerce client id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Customer registration rejected."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/pickup-branches": {
            "get": {
                "operationId": "get_api_store_pickup_branches",
                "tags": [
                    "Pickup Branches"
                ],
                "summary": "List pickup branches",
                "description": "One row per store-enabled warehouse with its pickup configuration.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PickupBranchesController@index",
                "x-source": "app/Http/Controllers/Api/Store/PickupBranchesController.php#L19-L48",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting",
                    "StorePickupBranch",
                    "Warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`branches[] {warehouse_id, name, city, country, active, address, hours, contact, notes, sort_order}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouse_id": {
                                            "type": "integer"
                                        },
                                        "name": {},
                                        "city": {},
                                        "country": {},
                                        "active": {
                                            "type": "boolean"
                                        },
                                        "address": {},
                                        "hours": {},
                                        "contact": {},
                                        "notes": {},
                                        "sort_order": {
                                            "type": "integer"
                                        },
                                        "branches": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_pickup_branches",
                "tags": [
                    "Pickup Branches"
                ],
                "summary": "Save pickup branches",
                "description": "Bulk upsert of every row; warehouses not enabled for the store are ignored.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\PickupBranchesController@save",
                "x-source": "app/Http/Controllers/Api/Store/PickupBranchesController.php#L51-L92",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting",
                    "StorePickupBranch"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "branches": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "active": {
                                                    "type": "boolean",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "boolean"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Offer pickup here."
                                                },
                                                "address": {
                                                    "type": "string",
                                                    "maxLength": 255,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:255"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Pickup address."
                                                },
                                                "contact": {
                                                    "type": "string",
                                                    "maxLength": 100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Contact phone."
                                                },
                                                "hours": {
                                                    "type": "string",
                                                    "maxLength": 191,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:191"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Opening hours."
                                                },
                                                "notes": {
                                                    "type": "string",
                                                    "maxLength": 1000,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:1000"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Instructions."
                                                },
                                                "sort_order": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Order."
                                                },
                                                "warehouse_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Warehouse."
                                                }
                                            },
                                            "required": [
                                                "warehouse_id"
                                            ]
                                        },
                                        "x-conditional": [
                                            "present"
                                        ],
                                        "x-laravel-rules": [
                                            "present",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Rows."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/popups": {
            "get": {
                "operationId": "get_api_store_popups",
                "tags": [
                    "Store Popups"
                ],
                "summary": "List popups",
                "description": "Paginated storefront popups with schedule, delay and enabled flag.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StorePopupsController@index",
                "x-source": "app/Http/Controllers/Api/Store/StorePopupsController.php#L13-L24",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StorePopup"
                ],
                "responses": {
                    "200": {
                        "description": "`popups[]` and `locales`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "popups": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "locales": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_popups",
                "tags": [
                    "Store Popups"
                ],
                "summary": "Create a popup",
                "description": "Creates a popup (title, message, image, call-to-action, delay, schedule, translations).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StorePopupsController@store",
                "x-source": "app/Http/Controllers/Api/Store/StorePopupsController.php#L26-L36",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StorePopup"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "cta_label": {
                                        "type": "string",
                                        "maxLength": 80,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:80"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Button label."
                                    },
                                    "cta_label_translations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 80,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "string",
                                                "max:80"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-locale labels."
                                    },
                                    "cta_url": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Button URL."
                                    },
                                    "delay_seconds": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Delay for the `delay` trigger (0–120)."
                                    },
                                    "enabled": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "0",
                                            "1"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Enabled."
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show until."
                                    },
                                    "frequency": {
                                        "type": "string",
                                        "enum": [
                                            "once",
                                            "session",
                                            "always"
                                        ],
                                        "description": "Frequency.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 4096,
                                        "x-laravel-rules": [
                                            "image",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "file",
                                            "validated"
                                        ],
                                        "description": "Image (max 4 MB)."
                                    },
                                    "message": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Body text."
                                    },
                                    "message_translations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 2000,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "string",
                                                "max:2000"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-locale messages."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Priority."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show from."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    },
                                    "title_translations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 150,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "string",
                                                "max:150"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-locale titles."
                                    },
                                    "trigger": {
                                        "type": "string",
                                        "enum": [
                                            "immediate",
                                            "delay",
                                            "exit"
                                        ],
                                        "description": "Trigger.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "announcement",
                                            "subscription",
                                            "sale"
                                        ],
                                        "description": "Popup type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "frequency",
                                    "trigger",
                                    "type",
                                    "type",
                                    "trigger",
                                    "frequency"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/popups/{id}": {
            "delete": {
                "operationId": "delete_api_store_popups_id",
                "tags": [
                    "Store Popups"
                ],
                "summary": "Delete a popup",
                "description": "Deletes a popup and its image.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StorePopupsController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/StorePopupsController.php#L55-L62",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StorePopup"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Popup id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_popups_id",
                "tags": [
                    "Store Popups"
                ],
                "summary": "Update a popup",
                "description": "Multipart POST (for the image). Same fields as create.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\StorePopupsController@update",
                "x-source": "app/Http/Controllers/Api/Store/StorePopupsController.php#L38-L53",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StorePopup"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Popup id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "cta_label": {
                                        "type": "string",
                                        "maxLength": 80,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:80"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Button label."
                                    },
                                    "cta_label_translations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 80,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "string",
                                                "max:80"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-locale labels."
                                    },
                                    "cta_url": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Button URL."
                                    },
                                    "delay_seconds": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Delay for the `delay` trigger (0–120)."
                                    },
                                    "enabled": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "0",
                                            "1"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "read",
                                            "validated"
                                        ],
                                        "description": "Enabled."
                                    },
                                    "ends_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-rules": [
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date",
                                            "after_or_equal:starts_at"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show until."
                                    },
                                    "frequency": {
                                        "type": "string",
                                        "enum": [
                                            "once",
                                            "session",
                                            "always"
                                        ],
                                        "description": "Frequency.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "image",
                                        "maxLength": 4096,
                                        "x-laravel-rules": [
                                            "image",
                                            "max:4096"
                                        ],
                                        "x-sources": [
                                            "file",
                                            "validated"
                                        ],
                                        "description": "Image (max 4 MB)."
                                    },
                                    "message": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Body text."
                                    },
                                    "message_translations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 2000,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "string",
                                                "max:2000"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-locale messages."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Priority."
                                    },
                                    "starts_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Show from."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Title."
                                    },
                                    "title_translations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 150,
                                            "nullable": true,
                                            "x-laravel-rules": [
                                                "nullable",
                                                "string",
                                                "max:150"
                                            ]
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Per-locale titles."
                                    },
                                    "trigger": {
                                        "type": "string",
                                        "enum": [
                                            "immediate",
                                            "delay",
                                            "exit"
                                        ],
                                        "description": "Trigger.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "announcement",
                                            "subscription",
                                            "sale"
                                        ],
                                        "description": "Popup type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "frequency",
                                    "trigger",
                                    "type",
                                    "type",
                                    "trigger",
                                    "frequency"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/questions": {
            "get": {
                "operationId": "get_api_store_questions",
                "tags": [
                    "Product Questions"
                ],
                "summary": "List product questions",
                "description": "Paginated product questions asked by shoppers with product, customer, answer and status. Filter by `status`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ProductQuestionsController@index",
                "x-source": "app/Http/Controllers/Api/Store/ProductQuestionsController.php#L17-L52",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProductQuestion"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "product_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Product."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `published`, `rejected`."
                    },
                    {
                        "name": "unanswered",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "boolean"
                        },
                        "description": "`1` = without answer."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "pending_count": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/questions/{id}": {
            "delete": {
                "operationId": "delete_api_store_questions_id",
                "tags": [
                    "Product Questions"
                ],
                "summary": "Delete a question",
                "description": "Deletes a question.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ProductQuestionsController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/ProductQuestionsController.php#L94-L101",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ProductQuestion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Question id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/questions/{id}/answer": {
            "post": {
                "operationId": "post_api_store_questions_id_answer",
                "tags": [
                    "Product Questions"
                ],
                "summary": "Answer a question",
                "description": "Stores the answer and publishes unless `publish` is false.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ProductQuestionsController@answer",
                "x-source": "app/Http/Controllers/Api/Store/ProductQuestionsController.php#L58-L77",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ProductQuestion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Question id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "answer": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Answer text (max 2000)."
                                    },
                                    "publish": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Publish now (default true)."
                                    }
                                },
                                "required": [
                                    "answer"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `question`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "question": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/questions/{id}/status": {
            "post": {
                "operationId": "post_api_store_questions_id_status",
                "tags": [
                    "Product Questions"
                ],
                "summary": "Set question status",
                "description": "Publishes, hides or rejects a question (`status`: `pending`, `approved`, `rejected`).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ProductQuestionsController@setStatus",
                "x-source": "app/Http/Controllers/Api/Store/ProductQuestionsController.php#L79-L92",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ProductQuestion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Question id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "published",
                                            "rejected"
                                        ],
                                        "description": "Status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "status",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/quote-requests": {
            "get": {
                "operationId": "get_api_store_quote_requests",
                "tags": [
                    "Quote Requests"
                ],
                "summary": "List quote requests",
                "description": "GET /store/quote-requests — admin list.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\QuoteRequestsController@index",
                "x-source": "app/Http/Controllers/Api/Store/QuoteRequestsController.php#L58-L100",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "StoreQuoteRequest"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`new`, `handled`, `closed`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]`, `meta`, `counts`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "counts": {
                                            "type": "object",
                                            "properties": {
                                                "new": {
                                                    "type": "integer"
                                                },
                                                "handled": {
                                                    "type": "integer"
                                                },
                                                "closed": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/quote-requests/{id}": {
            "delete": {
                "operationId": "delete_api_store_quote_requests_id",
                "tags": [
                    "Quote Requests"
                ],
                "summary": "Delete a quote request",
                "description": "Deletes a quote request.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\QuoteRequestsController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/QuoteRequestsController.php#L115-L122",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreQuoteRequest"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Request id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/quote-requests/{id}/status": {
            "post": {
                "operationId": "post_api_store_quote_requests_id_status",
                "tags": [
                    "Quote Requests"
                ],
                "summary": "Set quote request status",
                "description": "Sets the quote-request status (`pending`, `quoted`, `accepted`, `rejected`, `closed`).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\QuoteRequestsController@setStatus",
                "x-source": "app/Http/Controllers/Api/Store/QuoteRequestsController.php#L102-L113",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "StoreQuoteRequest"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Request id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "new",
                                            "handled",
                                            "closed"
                                        ],
                                        "description": "Status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "status",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/returns": {
            "get": {
                "operationId": "get_api_store_returns",
                "tags": [
                    "Online Order Returns"
                ],
                "summary": "List return / cancellation requests",
                "description": "Paginated with order ref, items and totals.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ReturnsController@index",
                "x-source": "app/Http/Controllers/Api/Store/ReturnsController.php#L18-L61",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "OnlineOrderReturn"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 15)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`requested`, `approved`, `rejected`, `refunded`."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`cancellation` or `return`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/returns/{id}/approve": {
            "post": {
                "operationId": "post_api_store_returns_id_approve",
                "tags": [
                    "Online Order Returns"
                ],
                "summary": "Approve a return request",
                "description": "Approves and processes the refund (amount defaults to the request total) to the wallet or the original method per settings.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ReturnsController@approve",
                "x-source": "app/Http/Controllers/Api/Store/ReturnsController.php#L63-L91",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "OnlineOrderReturn"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Return id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "admin_note": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Internal note."
                                    },
                                    "refund_amount": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Override refund amount."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success`, `status`, `refund_amount`, `refund_reference`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {},
                                        "refund_amount": {
                                            "type": "number"
                                        },
                                        "refund_reference": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/returns/{id}/reject": {
            "post": {
                "operationId": "post_api_store_returns_id_reject",
                "tags": [
                    "Online Order Returns"
                ],
                "summary": "Reject a return request",
                "description": "Rejects a return request with a `reason`; the customer is notified.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ReturnsController@reject",
                "x-source": "app/Http/Controllers/Api/Store/ReturnsController.php#L93-L108",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "OnlineOrderReturn"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Return id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "admin_note": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reason / note."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success` and `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/reviews": {
            "get": {
                "operationId": "get_api_store_reviews",
                "tags": [
                    "Product Reviews"
                ],
                "summary": "List product reviews",
                "description": "Paginated with `counts` per status.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ProductReviewsController@index",
                "x-source": "app/Http/Controllers/Api/Store/ProductReviewsController.php#L13-L56",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ProductReview"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "rating",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "1–5."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `approved`, `rejected`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]`, `meta`, `counts`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "counts": {
                                            "type": "object",
                                            "properties": {
                                                "pending": {
                                                    "type": "integer"
                                                },
                                                "approved": {
                                                    "type": "integer"
                                                },
                                                "rejected": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/reviews/{id}": {
            "delete": {
                "operationId": "delete_api_store_reviews_id",
                "tags": [
                    "Product Reviews"
                ],
                "summary": "Delete a review",
                "description": "Deletes a product review.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ProductReviewsController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/ProductReviewsController.php#L73-L80",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ProductReview"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Review id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/reviews/{id}/status": {
            "post": {
                "operationId": "post_api_store_reviews_id_status",
                "tags": [
                    "Product Reviews"
                ],
                "summary": "Set review status",
                "description": "Approves, hides or rejects a review (`status`: `pending`, `approved`, `rejected`).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ProductReviewsController@setStatus",
                "x-source": "app/Http/Controllers/Api/Store/ProductReviewsController.php#L58-L71",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ProductReview"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Review id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "pending",
                                            "approved",
                                            "rejected"
                                        ],
                                        "description": "Status.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "status",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/shipping-methods": {
            "get": {
                "operationId": "get_api_store_shipping_methods",
                "tags": [
                    "Shipping Methods"
                ],
                "summary": "List shipping methods",
                "description": "Methods with their `countries[]`, plus `country_options`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingMethodsController@index",
                "x-source": "app/Http/Controllers/Api/Store/ShippingMethodsController.php#L13-L40",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingMethod"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Name."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`methods[]` and `country_options`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "country_options": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_shipping_methods",
                "tags": [
                    "Shipping Methods"
                ],
                "summary": "Create a shipping method",
                "description": "Creates a shipping method (name, description, cost, free-above threshold, estimated days, active flag).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingMethodsController@store",
                "x-source": "app/Http/Controllers/Api/Store/ShippingMethodsController.php#L42-L61",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingMethod"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active (default true)."
                                    },
                                    "countries": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Country codes/names the method applies to (empty = everywhere).",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Flat price."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    }
                                },
                                "required": [
                                    "name",
                                    "price"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/shipping-methods/{id}": {
            "delete": {
                "operationId": "delete_api_store_shipping_methods_id",
                "tags": [
                    "Shipping Methods"
                ],
                "summary": "Delete a shipping method",
                "description": "Deletes a shipping method.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingMethodsController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/ShippingMethodsController.php#L83-L90",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingMethod"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Method id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_shipping_methods_id",
                "tags": [
                    "Shipping Methods"
                ],
                "summary": "Update a shipping method",
                "description": "Updates a shipping method with the same fields as creation.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingMethodsController@update",
                "x-source": "app/Http/Controllers/Api/Store/ShippingMethodsController.php#L63-L81",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingMethod"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Method id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "countries": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Countries (full replacement).",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Price."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    }
                                },
                                "required": [
                                    "name",
                                    "price"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/shipping-zones": {
            "get": {
                "operationId": "get_api_store_shipping_zones",
                "tags": [
                    "Shipping Zones"
                ],
                "summary": "List shipping zones",
                "description": "Zones with `locations[]` and `rates[]`, plus `countries` / `subdivisions` option lists and the allowed `rate_types`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingZonesController@index",
                "x-source": "app/Http/Controllers/Api/Store/ShippingZonesController.php#L23-L37",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingZone"
                ],
                "responses": {
                    "200": {
                        "description": "`zones[]`, `countries`, `subdivisions`, `rate_types`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "zones": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "countries": {},
                                        "subdivisions": {},
                                        "rate_types": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_shipping_zones",
                "tags": [
                    "Shipping Zones"
                ],
                "summary": "Create a shipping zone",
                "description": "Creates a shipping zone: name and the countries/states it covers. Rates are added with the `…/rates` endpoints.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingZonesController@store",
                "x-source": "app/Http/Controllers/Api/Store/ShippingZonesController.php#L39-L56",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingZone"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "locations": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "country": {
                                                    "type": "string",
                                                    "maxLength": 100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Country name / code."
                                                },
                                                "state": {
                                                    "type": "string",
                                                    "maxLength": 100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "State (optional = whole country)."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Covered locations."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Zone name."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/shipping-zones/{id}": {
            "delete": {
                "operationId": "delete_api_store_shipping_zones_id",
                "tags": [
                    "Shipping Zones"
                ],
                "summary": "Delete a shipping zone",
                "description": "Rates are deactivated and detached (orders keep referencing them); locations are removed.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingZonesController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/ShippingZonesController.php#L76-L89",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingZone"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Zone id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_shipping_zones_id",
                "tags": [
                    "Shipping Zones"
                ],
                "summary": "Update a shipping zone",
                "description": "Updates a zone's name and locations (the list replaces the previous one).",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingZonesController@update",
                "x-source": "app/Http/Controllers/Api/Store/ShippingZonesController.php#L58-L74",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingZone"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Zone id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "locations": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "country": {
                                                    "type": "string",
                                                    "maxLength": 100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Country name / code."
                                                },
                                                "state": {
                                                    "type": "string",
                                                    "maxLength": 100,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "string",
                                                        "max:100"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "State (optional = whole country)."
                                                }
                                            }
                                        },
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Locations (full replacement)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/shipping-zones/{zone}/rates": {
            "post": {
                "operationId": "post_api_store_shipping_zones_zone_rates",
                "tags": [
                    "Shipping Zones"
                ],
                "summary": "Add a rate to a zone",
                "description": "Adds a rate to a zone: name, type (flat, per weight, free above), cost and conditions.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingZonesController@storeRate",
                "x-source": "app/Http/Controllers/Api/Store/ShippingZonesController.php#L93-L103",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingZone",
                    "ShippingMethod"
                ],
                "parameters": [
                    {
                        "name": "zone",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Zone id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "max_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-rules": [
                                            "gte:min_value"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "gte:min_value"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Band upper bound (>= min)."
                                    },
                                    "min_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Band lower bound."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Rate label (e.g. *Standard*)."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Shipping price."
                                    },
                                    "rate_type": {
                                        "type": "string",
                                        "enum": [
                                            "flat",
                                            "price",
                                            "weight"
                                        ],
                                        "description": "Rate type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    }
                                },
                                "required": [
                                    "name",
                                    "price",
                                    "rate_type",
                                    "rate_type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/shipping-zones/{zone}/rates/{rate}": {
            "delete": {
                "operationId": "delete_api_store_shipping_zones_zone_rates_rate",
                "tags": [
                    "Shipping Zones"
                ],
                "summary": "Delete a rate",
                "description": "Soft delete so past orders stay intact.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingZonesController@destroyRate",
                "x-source": "app/Http/Controllers/Api/Store/ShippingZonesController.php#L115-L124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingMethod"
                ],
                "parameters": [
                    {
                        "name": "zone",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Zone id."
                    },
                    {
                        "name": "rate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Rate id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_shipping_zones_zone_rates_rate",
                "tags": [
                    "Shipping Zones"
                ],
                "summary": "Update a rate",
                "description": "Updates a zone rate.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\ShippingZonesController@updateRate",
                "x-source": "app/Http/Controllers/Api/Store/ShippingZonesController.php#L105-L113",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "ShippingMethod"
                ],
                "parameters": [
                    {
                        "name": "zone",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Zone id."
                    },
                    {
                        "name": "rate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Rate id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "max_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-rules": [
                                            "gte:min_value"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0",
                                            "gte:min_value"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Max."
                                    },
                                    "min_value": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Min."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label."
                                    },
                                    "price": {
                                        "type": "number",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Price."
                                    },
                                    "rate_type": {
                                        "type": "string",
                                        "enum": [
                                            "flat",
                                            "price",
                                            "weight"
                                        ],
                                        "description": "Rate type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "sort_order": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Order."
                                    }
                                },
                                "required": [
                                    "name",
                                    "price",
                                    "rate_type",
                                    "rate_type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/sslcommerz/cancel": {
            "get": {
                "operationId": "get_api_store_sslcommerz_cancel",
                "x-methods": [
                    "GET",
                    "POST"
                ],
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "SSLCommerz cancel URL",
                "description": "POST|GET /store/sslcommerz/cancel — the customer backed out on the hosted page. Cancel the pending order and send them back to checkout. /",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@sslcommerzCancel",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L1096-L1106",
                "x-route-name": "store.sslcommerz.cancel",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "tran_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Transaction id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "post_api_store_sslcommerz_cancel",
                "x-methods": [
                    "GET",
                    "POST"
                ],
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "SSLCommerz cancel URL",
                "description": "POST|GET /store/sslcommerz/cancel — the customer backed out on the hosted page. Cancel the pending order and send them back to checkout. /",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@sslcommerzCancel",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L1096-L1106",
                "x-route-name": "store.sslcommerz.cancel",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "tran_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Transaction id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": [],
                "x-alias-of": "get"
            }
        },
        "/api/store/sslcommerz/fail": {
            "get": {
                "operationId": "get_api_store_sslcommerz_fail",
                "x-methods": [
                    "GET",
                    "POST"
                ],
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "SSLCommerz fail URL",
                "description": "POST|GET /store/sslcommerz/fail — the payment attempt failed on the hosted page. The pending order is resolved by the unguessable tran_id. /",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@sslcommerzFail",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L1080-L1090",
                "x-route-name": "store.sslcommerz.fail",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "tran_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Transaction id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "post_api_store_sslcommerz_fail",
                "x-methods": [
                    "GET",
                    "POST"
                ],
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "SSLCommerz fail URL",
                "description": "POST|GET /store/sslcommerz/fail — the payment attempt failed on the hosted page. The pending order is resolved by the unguessable tran_id. /",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@sslcommerzFail",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L1080-L1090",
                "x-route-name": "store.sslcommerz.fail",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "tran_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Transaction id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": [],
                "x-alias-of": "get"
            }
        },
        "/api/store/sslcommerz/return": {
            "get": {
                "operationId": "get_api_store_sslcommerz_return",
                "x-methods": [
                    "GET",
                    "POST"
                ],
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "SSLCommerz success URL",
                "description": "GET or POST. Validates `val_id` / `tran_id` and the amount with the validation API before marking paid.",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@sslcommerzReturn",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L1027-L1074",
                "x-route-name": "store.sslcommerz.return",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "tran_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Transaction id."
                    },
                    {
                        "name": "val_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Validation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "post_api_store_sslcommerz_return",
                "x-methods": [
                    "GET",
                    "POST"
                ],
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "SSLCommerz success URL",
                "description": "GET or POST. Validates `val_id` / `tran_id` and the amount with the validation API before marking paid.",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@sslcommerzReturn",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L1027-L1074",
                "x-route-name": "store.sslcommerz.return",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "tran_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Transaction id."
                    },
                    {
                        "name": "val_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Validation id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": [],
                "x-alias-of": "get"
            }
        },
        "/api/store/subscribers": {
            "get": {
                "operationId": "get_api_store_subscribers",
                "tags": [
                    "Newsletter Subscribers"
                ],
                "summary": "List newsletter subscribers",
                "description": "Paginated newsletter subscribers with email, name, source and subscription date.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SubscriberController@index",
                "x-source": "app/Http/Controllers/Api/Store/SubscriberController.php#L11-L35",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Subscribers_view",
                        "policy": "SubscriberPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Subscriber"
                ],
                "parameters": [
                    {
                        "name": "dir",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Direction."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Column."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[] {id, email, created_at}` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "email": {},
                                        "created_at": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "integer"
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/subscribers/{id}": {
            "delete": {
                "operationId": "delete_api_store_subscribers_id",
                "tags": [
                    "Newsletter Subscribers"
                ],
                "summary": "Delete a subscriber",
                "description": "Removes a subscriber.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\SubscriberController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/SubscriberController.php#L37-L45",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Subscribers_view",
                        "policy": "SubscriberPolicy"
                    }
                ],
                "x-models": [
                    "Subscriber"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Subscriber id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/tax-rates": {
            "get": {
                "operationId": "get_api_store_tax_rates",
                "tags": [
                    "Tax Rates"
                ],
                "summary": "List tax rates",
                "description": "Store tax rates with name, rate %, country/state scope and priority.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\TaxRatesController@index",
                "x-source": "app/Http/Controllers/Api/Store/TaxRatesController.php#L12-L42",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "TaxRate"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Country, state or name."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`rates[]`, `country_options`, `subdivisions`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rates": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "country_options": {},
                                        "subdivisions": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_tax_rates",
                "tags": [
                    "Tax Rates"
                ],
                "summary": "Create a tax rate",
                "description": "Creates a tax rate applied at storefront checkout for the matching country/state.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\TaxRatesController@store",
                "x-source": "app/Http/Controllers/Api/Store/TaxRatesController.php#L44-L52",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "TaxRate"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "country": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Country."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label (e.g. *VAT*)."
                                    },
                                    "rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Percentage 0–100."
                                    },
                                    "state": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "State / region (optional = whole country)."
                                    }
                                },
                                "required": [
                                    "country",
                                    "rate"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/tax-rates/{id}": {
            "delete": {
                "operationId": "delete_api_store_tax_rates_id",
                "tags": [
                    "Tax Rates"
                ],
                "summary": "Delete a tax rate",
                "description": "Deletes a tax rate.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\TaxRatesController@destroy",
                "x-source": "app/Http/Controllers/Api/Store/TaxRatesController.php#L64-L71",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "TaxRate"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Rate id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_store_tax_rates_id",
                "tags": [
                    "Tax Rates"
                ],
                "summary": "Update a tax rate",
                "description": "Updates a tax rate.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\TaxRatesController@update",
                "x-source": "app/Http/Controllers/Api/Store/TaxRatesController.php#L54-L62",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "Store_settings_view",
                        "policy": "StoreSettingPolicy"
                    }
                ],
                "x-models": [
                    "TaxRate"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Rate id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "country": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Country."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Label."
                                    },
                                    "rate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Percentage."
                                    },
                                    "state": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "State."
                                    }
                                },
                                "required": [
                                    "country",
                                    "rate"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallet-withdrawals": {
            "get": {
                "operationId": "get_api_store_wallet_withdrawals",
                "tags": [
                    "Wallet Withdrawals"
                ],
                "summary": "List withdrawal requests",
                "description": "Paginated wallet withdrawal requests from shoppers with amount, payout details, status and dates. Filter by `status`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletWithdrawalController@index",
                "x-source": "app/Http/Controllers/Api/Store/WalletWithdrawalController.php#L21-L55",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "WalletWithdrawalPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "WalletWithdrawal"
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `approved`, `rejected`, `paid`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[] {id, wallet_id, client_name, client_email, amount, status, method, destination, note, …}` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallet-withdrawals/{id}/approve": {
            "post": {
                "operationId": "post_api_store_wallet_withdrawals_id_approve",
                "tags": [
                    "Wallet Withdrawals"
                ],
                "summary": "Approve a withdrawal",
                "description": "Debits the wallet (row-locked, idempotent) and sets `approved`.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletWithdrawalController@approve",
                "x-source": "app/Http/Controllers/Api/Store/WalletWithdrawalController.php#L62-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "WalletWithdrawalPolicy"
                    }
                ],
                "x-models": [
                    "WalletWithdrawal"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Withdrawal id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Admin note."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Not pending / insufficient balance."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallet-withdrawals/{id}/paid": {
            "post": {
                "operationId": "post_api_store_wallet_withdrawals_id_paid",
                "tags": [
                    "Wallet Withdrawals"
                ],
                "summary": "Mark a withdrawal paid out",
                "description": "Mark an approved withdrawal as paid out. /",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletWithdrawalController@markPaid",
                "x-source": "app/Http/Controllers/Api/Store/WalletWithdrawalController.php#L99-L115",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "WalletWithdrawalPolicy"
                    }
                ],
                "x-models": [
                    "WalletWithdrawal"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Withdrawal id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Not approved.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallet-withdrawals/{id}/reject": {
            "post": {
                "operationId": "post_api_store_wallet_withdrawals_id_reject",
                "tags": [
                    "Wallet Withdrawals"
                ],
                "summary": "Reject a withdrawal",
                "description": "No balance change.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletWithdrawalController@reject",
                "x-source": "app/Http/Controllers/Api/Store/WalletWithdrawalController.php#L120-L137",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "WalletWithdrawalPolicy"
                    }
                ],
                "x-models": [
                    "WalletWithdrawal"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Withdrawal id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "note": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Reason."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Not pending.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallet/dashboard": {
            "get": {
                "operationId": "get_api_store_wallet_dashboard",
                "tags": [
                    "Customer Wallets"
                ],
                "summary": "E-wallet dashboard",
                "description": "`stats` (wallet counts, balance in circulation, credits / debits, pending withdrawals), `top_wallets`, `recent_transactions`, `pending_requests`, the store `currency` and whether the wallet payment method exists.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletController@index",
                "x-source": "app/Http/Controllers/Api/Store/WalletController.php#L26-L87",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "ewallet",
                        "policy": "WalletPolicy"
                    }
                ],
                "x-models": [
                    "Wallet",
                    "WalletTransaction",
                    "WalletWithdrawal",
                    "StoreSetting"
                ],
                "responses": {
                    "200": {
                        "description": "Dashboard object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "currency": {
                                            "type": "string"
                                        },
                                        "wallet_payment_method_exists": {},
                                        "stats": {
                                            "type": "object",
                                            "properties": {
                                                "total_wallets": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "active_wallets": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "in_circulation": {},
                                                "total_credits": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "total_debits": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "pending_withdrawals": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "pending_amount": {},
                                                "total_withdrawn": {}
                                            }
                                        },
                                        "top_wallets": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "recent_transactions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "pending_requests": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallet/settings": {
            "get": {
                "operationId": "get_api_store_wallet_settings",
                "tags": [
                    "Customer Wallets"
                ],
                "summary": "Get wallet settings",
                "description": "E-Wallet settings only (dedicated module settings page). /",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletController@settings",
                "x-source": "app/Http/Controllers/Api/Store/WalletController.php#L210-L224",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "ewallet",
                        "policy": "WalletPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`wallet_enabled`, `wallet_allow_negative`, `wallet_refund_destination`, `wallet_withdrawal_enabled`, `wallet_min_withdrawal`, `wallet_payment_method_exists`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "wallet_enabled": {
                                            "type": "boolean"
                                        },
                                        "wallet_allow_negative": {
                                            "type": "boolean"
                                        },
                                        "wallet_refund_destination": {
                                            "type": "string"
                                        },
                                        "wallet_withdrawal_enabled": {
                                            "type": "boolean"
                                        },
                                        "wallet_min_withdrawal": {
                                            "type": "number"
                                        },
                                        "wallet_payment_method_exists": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_store_wallet_settings",
                "tags": [
                    "Customer Wallets"
                ],
                "summary": "Save wallet settings",
                "description": "Save E-Wallet settings (only the wallet_* columns). /",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletController@updateSettings",
                "x-source": "app/Http/Controllers/Api/Store/WalletController.php#L229-L253",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "ewallet",
                        "policy": "WalletPolicy"
                    }
                ],
                "x-models": [
                    "StoreSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "wallet_allow_negative": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "0",
                                            "1"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Allow negative balances."
                                    },
                                    "wallet_enabled": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "0",
                                            "1"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable wallets."
                                    },
                                    "wallet_min_withdrawal": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Minimum withdrawal amount."
                                    },
                                    "wallet_refund_destination": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "wallet",
                                            "original"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:wallet,original"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`wallet` or `original`."
                                    },
                                    "wallet_withdrawal_enabled": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "0",
                                            "1"
                                        ],
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "in:0,1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Allow withdrawal requests."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallets": {
            "get": {
                "operationId": "get_api_store_wallets",
                "tags": [
                    "Customer Wallets"
                ],
                "summary": "List wallets",
                "description": "Paginated wallets ordered by balance.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletController@wallets",
                "x-source": "app/Http/Controllers/Api/Store/WalletController.php#L92-L125",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "ewallet",
                        "policy": "WalletPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Wallet"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 10)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallets/{id}": {
            "get": {
                "operationId": "get_api_store_wallets_id",
                "tags": [
                    "Customer Wallets"
                ],
                "summary": "Get a wallet",
                "description": "Wallet header and its last 200 transactions.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletController@show",
                "x-source": "app/Http/Controllers/Api/Store/WalletController.php#L130-L154",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "ewallet",
                        "policy": "WalletPolicy"
                    }
                ],
                "x-models": [
                    "Wallet"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Wallet id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`wallet` and `transactions[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "wallet": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "client_id": {},
                                                "client_name": {},
                                                "client_email": {},
                                                "balance": {
                                                    "type": "number"
                                                },
                                                "currency": {},
                                                "status": {}
                                            }
                                        },
                                        "transactions": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallets/{id}/adjust": {
            "post": {
                "operationId": "post_api_store_wallets_id_adjust",
                "tags": [
                    "Customer Wallets"
                ],
                "summary": "Adjust a wallet balance",
                "description": "Manual credit or debit with a note; recorded as an `adjustment` transaction.",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletController@adjust",
                "x-source": "app/Http/Controllers/Api/Store/WalletController.php#L159-L190",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "ewallet",
                        "policy": "WalletPolicy"
                    }
                ],
                "x-models": [
                    "Wallet"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Wallet id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Amount (> 0)."
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reason."
                                    },
                                    "type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "credit",
                                            "debit"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:credit,debit"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`credit` or `debit`."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, new `balance`, `transaction`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "balance": {
                                            "type": "number"
                                        },
                                        "transaction": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/wallets/{id}/status": {
            "post": {
                "operationId": "post_api_store_wallets_id_status",
                "tags": [
                    "Customer Wallets"
                ],
                "summary": "Freeze / unfreeze a wallet",
                "description": "Freeze / unfreeze a wallet. /",
                "x-section": "Online Store (Admin)",
                "x-surface": "admin",
                "x-controller": "Api\\Store\\WalletController@setStatus",
                "x-source": "app/Http/Controllers/Api/Store/WalletController.php#L195-L205",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "ewallet",
                        "policy": "WalletPolicy"
                    }
                ],
                "x-models": [
                    "Wallet"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Wallet id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "frozen"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,frozen"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`active` or `frozen`."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store/webhooks/flutterwave": {
            "post": {
                "operationId": "post_api_store_webhooks_flutterwave",
                "tags": [
                    "Payment Gateway Webhooks"
                ],
                "summary": "Flutterwave webhook",
                "description": "Verified with the `verif-hash` header (secret hash).",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\WebhookController@flutterwave",
                "x-source": "app/Http/Controllers/Api/Store/WebhookController.php#L48-L56",
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/api/store/webhooks/paypal": {
            "post": {
                "operationId": "post_api_store_webhooks_paypal",
                "tags": [
                    "Payment Gateway Webhooks"
                ],
                "summary": "PayPal webhook",
                "description": "Verified with the `PAYPAL-TRANSMISSION-SIG` header and the configured webhook id.",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\WebhookController@paypal",
                "x-source": "app/Http/Controllers/Api/Store/WebhookController.php#L28-L36",
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/api/store/webhooks/paystack": {
            "post": {
                "operationId": "post_api_store_webhooks_paystack",
                "tags": [
                    "Payment Gateway Webhooks"
                ],
                "summary": "Paystack webhook",
                "description": "Verified with the `x-paystack-signature` HMAC header.",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\WebhookController@paystack",
                "x-source": "app/Http/Controllers/Api/Store/WebhookController.php#L38-L46",
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/api/store/webhooks/razorpay": {
            "post": {
                "operationId": "post_api_store_webhooks_razorpay",
                "tags": [
                    "Payment Gateway Webhooks"
                ],
                "summary": "Razorpay webhook",
                "description": "Verified with the `X-Razorpay-Signature` header.",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\WebhookController@razorpay",
                "x-source": "app/Http/Controllers/Api/Store/WebhookController.php#L58-L66",
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/api/store/webhooks/sslcommerz": {
            "post": {
                "operationId": "post_api_store_webhooks_sslcommerz",
                "tags": [
                    "Payment Gateway Webhooks"
                ],
                "summary": "SSLCommerz IPN",
                "description": "Form-encoded IPN authenticated by the `verify_sign` in the body; a paid IPN is still confirmed via the validation API before the order is marked paid.",
                "x-section": "Storefront",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Api\\Store\\WebhookController@sslcommerz",
                "x-source": "app/Http/Controllers/Api/Store/WebhookController.php#L68-L111",
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "Error"
                    }
                },
                "security": []
            }
        },
        "/api/store_count_stock": {
            "post": {
                "operationId": "post_api_store_count_stock",
                "tags": [
                    "Products"
                ],
                "summary": "Generate a stock-count sheet",
                "description": "Builds an Excel sheet listing every product (and variant) in the warehouse with its current quantity, optionally limited to one category, saves it to `/images/count_stock/` and records the export in the stock-count history. The sheet is meant to be printed and filled in during a physical count.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "ProductsController@store_count_stock",
                "x-source": "app/Http/Controllers/ProductsController.php#L4055-L4123",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "count_stock",
                        "slug": "count_stock",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "product_warehouse",
                    "ProductVariant",
                    "CountStock"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Optional category filter."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Count date (`YYYY-MM-DD`)."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse to count."
                                    }
                                },
                                "required": [
                                    "date",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "date": "2026-09-06",
                                "warehouse_id": 1,
                                "category_id": null
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }` – the file appears in `GET /api/count_stock`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store_import_purchases": {
            "post": {
                "operationId": "post_api_store_import_purchases",
                "tags": [
                    "Purchases"
                ],
                "summary": "Create a purchase from a CSV",
                "description": "Creates a purchase whose lines come from the CSV (`productcode`, `qty`); cost and purchase unit are taken from the product. For batch-tracked products send `batches_by_code`, a JSON object mapping product code → array of `{batch_no, expiry_date, mfg_date, qty, unit_cost}`. Stock is added when `statut` is `received`.",
                "x-section": "Purchases",
                "x-surface": "admin",
                "x-controller": "PurchasesController@store_import_purchases",
                "x-source": "app/Http/Controllers/PurchasesController.php#L2213-L2326",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Purchases_add",
                        "policy": "PurchasePolicy"
                    }
                ],
                "x-models": [
                    "Purchase",
                    "Product",
                    "Unit",
                    "product_warehouse",
                    "PurchaseDetail"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batches_by_code": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "JSON object of batches per product code.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Date."
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Notes."
                                    },
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "CSV file."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`received`, `pending` or `ordered`.",
                                        "type": "string"
                                    },
                                    "supplier_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Supplier id. Required."
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "supplier_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and message, or `status: false` with validation `errors`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "msg": {
                                            "type": "string",
                                            "example": "Validation failed"
                                        },
                                        "status": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "errors": {},
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Purchase Created !!"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/store_import_sales": {
            "post": {
                "operationId": "post_api_store_import_sales",
                "tags": [
                    "Sales"
                ],
                "summary": "Create a sale from a CSV",
                "description": "Creates a sale whose lines come from the CSV (`productcode`, `qty`, optional `price`, `unit_sale_id`, `product_variant_id`). Stock is validated for every line first; if any product lacks stock the whole import is refused with the shortages listed. Prices default to the product price when absent.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SalesController@store_import_sales",
                "x-source": "app/Http/Controllers/SalesController.php#L2085-L2215",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "Sales_add",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "Sale",
                    "Product",
                    "Unit",
                    "SaleDetail",
                    "product_warehouse"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Customer id. Required."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sale date."
                                    },
                                    "discount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order discount amount."
                                    },
                                    "notes": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Free text."
                                    },
                                    "products": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "CSV file."
                                    },
                                    "sales_agent_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sales agent id."
                                    },
                                    "shipping": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Shipping cost.",
                                        "type": "number"
                                    },
                                    "statut": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`completed` (default), `pending` or `ordered`.",
                                        "type": "string"
                                    },
                                    "tax_rate": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Order tax percent."
                                    },
                                    "warehouse_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id. Required."
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`success` and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Sale created successfully."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/subcategories": {
            "get": {
                "operationId": "get_api_subcategories",
                "tags": [
                    "Sub-categories"
                ],
                "summary": "List sub-categories",
                "description": "Paginated sub-categories with their parent `category` (`id`, `name`). `search` matches the name. `SortField` whitelisted to `id`, `name`, `status`, `created_at`, `updated_at`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@index",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L15-L56",
                "x-route-name": "subcategories.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "subcategory",
                        "policy": "SubCategoryPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "SubCategory"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`subcategories[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "subcategories": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "subcategories": [
                                        {
                                            "id": 7,
                                            "category_id": 2,
                                            "name": "T-Shirts",
                                            "description": null,
                                            "status": true,
                                            "category": {
                                                "id": 2,
                                                "name": "Apparel"
                                            }
                                        }
                                    ],
                                    "totalRows": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_subcategories",
                "tags": [
                    "Sub-categories"
                ],
                "summary": "Create a sub-category",
                "description": "Creates a sub-category under `category_id`. The name must be unique within that category. `status` defaults to `true`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@store",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L61-L88",
                "x-route-name": "subcategories.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "subcategory",
                        "policy": "SubCategoryPolicy"
                    }
                ],
                "x-models": [
                    "SubCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category_id": {
                                        "type": "integer",
                                        "x-exists": "categories,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:categories,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Parent category id."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Optional description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "subcategories ->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190",
                                            "unique:subcategories ->where"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name, max 190, unique per category."
                                    },
                                    "status": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`true` active (default) / `false` hidden."
                                    }
                                },
                                "required": [
                                    "category_id",
                                    "name"
                                ]
                            },
                            "example": {
                                "category_id": 2,
                                "name": "T-Shirts",
                                "description": "Short-sleeve tops",
                                "status": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/subcategories/by-category/{category_id}": {
            "get": {
                "operationId": "get_api_subcategories_by_category_category_id",
                "tags": [
                    "Sub-categories"
                ],
                "summary": "List active sub-categories of a category",
                "description": "Active sub-categories (`status = true`) of one category as `{id, name, category_id}` ordered by name — used to fill the cascading picker on the product form.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@getByCategory",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L166-L174",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SubCategory"
                ],
                "parameters": [
                    {
                        "name": "category_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Parent category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of sub-categories.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                },
                                "example": [
                                    {
                                        "id": 7,
                                        "name": "T-Shirts",
                                        "category_id": 2
                                    }
                                ]
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/subcategories/delete/by_selection": {
            "post": {
                "operationId": "post_api_subcategories_delete_by_selection",
                "tags": [
                    "Sub-categories"
                ],
                "summary": "Delete several sub-categories",
                "description": "Hard-deletes every id in `selectedIds`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@delete_by_selection",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L151-L161",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "subcategory",
                        "policy": "SubCategoryPolicy"
                    }
                ],
                "x-models": [
                    "SubCategory"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of sub-category ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/subcategories/{subcategory}": {
            "delete": {
                "operationId": "delete_api_subcategories_subcategory",
                "tags": [
                    "Sub-categories"
                ],
                "summary": "Delete a sub-category",
                "description": "Deletes the sub-category (hard delete — this table has no soft deletes).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@destroy",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L138-L145",
                "x-route-name": "subcategories.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "subcategory",
                        "policy": "SubCategoryPolicy"
                    }
                ],
                "x-models": [
                    "SubCategory"
                ],
                "parameters": [
                    {
                        "name": "subcategory",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sub-category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_subcategories_subcategory",
                "tags": [
                    "Sub-categories"
                ],
                "summary": "Get a sub-category",
                "description": "Returns one sub-category with its parent `category`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@show",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L93-L98",
                "x-route-name": "subcategories.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SubCategory"
                ],
                "parameters": [
                    {
                        "name": "subcategory",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sub-category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Sub-category object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_subcategories_subcategory",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sub-categories"
                ],
                "summary": "Update a sub-category",
                "description": "Updates parent, name, description and status. Omitting `status` keeps the current value.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@update",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L103-L133",
                "x-route-name": "subcategories.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "subcategory",
                        "policy": "SubCategoryPolicy"
                    }
                ],
                "x-models": [
                    "SubCategory"
                ],
                "parameters": [
                    {
                        "name": "subcategory",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sub-category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category_id": {
                                        "type": "integer",
                                        "x-exists": "categories,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:categories,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Parent category id."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "subcategories ->where->ignore",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190",
                                            "unique:subcategories ->where->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name, unique per category."
                                    },
                                    "status": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    }
                                },
                                "required": [
                                    "category_id",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_subcategories_subcategory",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Sub-categories"
                ],
                "summary": "Update a sub-category",
                "description": "Updates parent, name, description and status. Omitting `status` keeps the current value.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "SubCategoryController@update",
                "x-source": "app/Http/Controllers/SubCategoryController.php#L103-L133",
                "x-route-name": "subcategories.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "subcategory",
                        "policy": "SubCategoryPolicy"
                    }
                ],
                "x-models": [
                    "SubCategory"
                ],
                "parameters": [
                    {
                        "name": "subcategory",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Sub-category id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "category_id": {
                                        "type": "integer",
                                        "x-exists": "categories,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:categories,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Parent category id."
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-unique": "subcategories ->where->ignore",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190",
                                            "unique:subcategories ->where->ignore"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name, unique per category."
                                    },
                                    "status": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    }
                                },
                                "required": [
                                    "category_id",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/subscriptions": {
            "get": {
                "operationId": "get_api_subscriptions",
                "tags": [
                    "Subscriptions"
                ],
                "summary": "List subscriptions",
                "description": "Paginated subscriptions. Rows: `id, client_name, product_name, warehouse_name, billing_cycle, total_cycles (label), total_cycles_count, remaining_cycles, cycle_type, price, price_per_cycle, price_per_unit, quantity, next_billing_date, status`. `search` matches customer or product name.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@index",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L17-L79",
                "x-route-name": "subscriptions.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "subscription_product",
                        "policy": "SubscriptionPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Subscription"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`active`, `canceled` or `completed`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`subscriptions[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "subscriptions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_subscriptions",
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Create a subscription",
                "description": "Creates a subscription from the nested `subscription` object. `remaining_cycles` is computed from `total_cycles`, `cycle_type` and `billing_cycle`. If `next_billing_date` is today an invoice (sale) is generated immediately. Returns HTTP **201**.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@store",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L101-L156",
                "x-route-name": "subscriptions.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "subscription_product",
                        "policy": "SubscriptionPolicy"
                    }
                ],
                "x-models": [
                    "Subscription"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "subscription": {
                                        "properties": {
                                            "billing_cycle": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "enum": [
                                                    "weekly",
                                                    "monthly",
                                                    "yearly"
                                                ],
                                                "x-laravel-rules": [
                                                    "required",
                                                    "in:weekly,monthly,yearly"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "How often to bill: `weekly`, `monthly`, `yearly`."
                                            },
                                            "client_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-exists": "clients,id",
                                                "x-laravel-rules": [
                                                    "required",
                                                    "exists:clients,id"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Customer id."
                                            },
                                            "cycle_type": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "enum": [
                                                    "weekly",
                                                    "monthly",
                                                    "yearly"
                                                ],
                                                "x-laravel-rules": [
                                                    "required",
                                                    "in:weekly,monthly,yearly"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Unit of the cycle count: `weekly`, `monthly`, `yearly`."
                                            },
                                            "next_billing_date": {
                                                "type": "string",
                                                "format": "date",
                                                "x-laravel-rules": [
                                                    "required",
                                                    "date"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "First billing date."
                                            },
                                            "price_per_cycle": {
                                                "type": "number",
                                                "minimum": 0,
                                                "x-laravel-rules": [
                                                    "required",
                                                    "numeric",
                                                    "min:0"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Amount billed each cycle."
                                            },
                                            "price_per_unit": {
                                                "type": "number",
                                                "minimum": 0,
                                                "x-laravel-rules": [
                                                    "required",
                                                    "numeric",
                                                    "min:0"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Unit price of the product."
                                            },
                                            "product_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-exists": "products,id",
                                                "x-laravel-rules": [
                                                    "required",
                                                    "exists:products,id"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Product id."
                                            },
                                            "quantity": {
                                                "type": "integer",
                                                "minimum": 1,
                                                "x-laravel-rules": [
                                                    "required",
                                                    "integer",
                                                    "min:1"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Quantity per cycle (≥ 1)."
                                            },
                                            "status": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "enum": [
                                                    "active",
                                                    "canceled",
                                                    "completed"
                                                ],
                                                "x-laravel-rules": [
                                                    "required",
                                                    "in:active,canceled,completed"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "`active`, `canceled`, `completed`."
                                            },
                                            "total_cycles": {
                                                "type": "integer",
                                                "minimum": 1,
                                                "x-laravel-rules": [
                                                    "required",
                                                    "integer",
                                                    "min:1"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Number of cycles (≥ 1)."
                                            },
                                            "warehouse_id": {
                                                "x-inferred": true,
                                                "type": "integer",
                                                "x-exists": "warehouses,id",
                                                "x-laravel-rules": [
                                                    "required",
                                                    "exists:warehouses,id"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Warehouse id."
                                            }
                                        },
                                        "required": [
                                            "billing_cycle",
                                            "client_id",
                                            "cycle_type",
                                            "next_billing_date",
                                            "price_per_cycle",
                                            "price_per_unit",
                                            "product_id",
                                            "quantity",
                                            "status",
                                            "total_cycles",
                                            "warehouse_id"
                                        ],
                                        "description": "Subscription fields as a nested object: `client_id`, `product_id`, `warehouse_id`, `quantity`, `price`, `frequency` (`daily`, `weekly`, `monthly`, `yearly`), `start_date`, `end_date`, `next_billing_date`, `status`, `notes`.",
                                        "type": "object"
                                    }
                                }
                            },
                            "example": {
                                "subscription": {
                                    "client_id": 3,
                                    "product_id": 5,
                                    "warehouse_id": 1,
                                    "total_cycles": 12,
                                    "cycle_type": "monthly",
                                    "billing_cycle": "monthly",
                                    "price_per_cycle": 99,
                                    "price_per_unit": 99,
                                    "quantity": 1,
                                    "next_billing_date": "2026-10-01",
                                    "status": "active"
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "201": {
                        "description": "`message` and the created `subscription`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Subscription created successfully!"
                                        },
                                        "subscription": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/subscriptions/create": {
            "get": {
                "operationId": "get_api_subscriptions_create",
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Get lookups for the subscription form",
                "description": "`clients`, `products` and `warehouses` (`id, name`).",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@create",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L83-L97",
                "x-route-name": "subscriptions.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "subscription_product",
                        "policy": "SubscriptionPolicy"
                    }
                ],
                "x-models": [
                    "Client",
                    "Product",
                    "Warehouse"
                ],
                "responses": {
                    "200": {
                        "description": "Lookups.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clients": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "products": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/subscriptions/{id}/status": {
            "put": {
                "operationId": "put_api_subscriptions_id_status",
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Change a subscription's status",
                "description": "Sets `status`; `canceled` stops future invoices.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@updateStatus",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L249-L263",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "subscription_product",
                        "policy": "SubscriptionPolicy"
                    }
                ],
                "x-models": [
                    "Subscription"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Subscription id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "canceled",
                                            "completed"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:active,canceled,completed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`active`, `canceled`, `completed`."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Confirmation message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Subscription status updated successfully!"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/subscriptions/{subscription}": {
            "delete": {
                "operationId": "delete_api_subscriptions_subscription",
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Delete a subscription",
                "description": "Soft-deletes the subscription; generated invoices are kept.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@destroy",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L238-L247",
                "x-route-name": "subscriptions.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "subscription_product",
                        "policy": "SubscriptionPolicy"
                    }
                ],
                "x-models": [
                    "Subscription"
                ],
                "parameters": [
                    {
                        "name": "subscription",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Subscription id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_subscriptions_subscription",
                "tags": [
                    "Subscriptions"
                ],
                "summary": "Get a subscription",
                "description": "The subscription with resolved names and the `invoices[]` generated so far (`sale_id, ref, date, total, status`), plus `invoiceFields` column metadata for the UI table.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@show",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L181-L226",
                "x-route-name": "subscriptions.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "subscription_product",
                        "policy": "SubscriptionPolicy"
                    }
                ],
                "x-models": [
                    "Subscription"
                ],
                "parameters": [
                    {
                        "name": "subscription",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Subscription id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`subscription`, `invoices[]`, `invoiceFields[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "subscription": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "date": {},
                                                "client": {},
                                                "client_id": {},
                                                "product": {},
                                                "product_id": {},
                                                "warehouse": {},
                                                "warehouse_id": {},
                                                "billing_cycle": {},
                                                "cycle_type": {},
                                                "total_cycles": {},
                                                "remaining_cycles": {},
                                                "price_per_cycle": {
                                                    "type": "number"
                                                },
                                                "price_per_cycle_raw": {},
                                                "price_per_unit": {},
                                                "quantity": {},
                                                "next_billing_date": {},
                                                "status": {}
                                            }
                                        },
                                        "invoices": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "invoiceFields": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sale_id": {},
                                        "ref": {},
                                        "date": {},
                                        "total": {
                                            "type": "number"
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_subscriptions_subscription",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Subscriptions"
                ],
                "summary": "(Not implemented) Update a subscription",
                "description": "Empty stub; returns an empty `200`. Only the status can be changed, through `PUT /api/subscriptions/{id}/status`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@update",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L230-L234",
                "x-route-name": "subscriptions.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "subscription",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Subscription id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_subscriptions_subscription",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Subscriptions"
                ],
                "summary": "(Not implemented) Update a subscription",
                "description": "Empty stub; returns an empty `200`. Only the status can be changed, through `PUT /api/subscriptions/{id}/status`.",
                "x-section": "Sales",
                "x-surface": "admin",
                "x-controller": "SubscriptionController@update",
                "x-source": "app/Http/Controllers/SubscriptionController.php#L230-L234",
                "x-route-name": "subscriptions.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "subscription",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Subscription id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/suppliers/import": {
            "post": {
                "operationId": "post_api_suppliers_import",
                "tags": [
                    "Suppliers"
                ],
                "summary": "Import suppliers from Excel",
                "description": "Bulk-creates suppliers from an `.xls`/`.xlsx` file (max 20 MB). Header row optional; recognised columns are `name`, `code`, `email`, `phone`, `adresse`/`address`, `country`, `city`, `tax_number`, `opening_balance`, `credit_limit`. All rows are validated first (`name` required, `code` unique in file and database); if any row fails nothing is written and the errors are returned with line numbers.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "ProvidersController@import",
                "x-source": "app/Http/Controllers/ProvidersController.php#L551-L711",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "Suppliers_import",
                        "slug": "Suppliers_import",
                        "policy": "ProviderPolicy"
                    }
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "Provider"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "suppliers": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:xls,xlsx",
                                        "maxLength": 20480,
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "mimes:xls,xlsx",
                                            "max:20480"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "The spreadsheet file (`multipart/form-data`)."
                                    }
                                },
                                "required": [
                                    "suppliers"
                                ],
                                "additionalProperties": true,
                                "x-accepts-all-input": true
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`imported` count.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "imported": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "status": true,
                                    "imported": 12
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sync-locale": {
            "post": {
                "operationId": "post_api_sync_locale",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Sync locale cookie",
                "description": "Stores the UI locale in a one-year cookie so server-rendered pages (PDFs, printable views) use the same language as the SPA. Reads `locale` from the body or the `X-Locale` header; only `ar` and `en` are honoured for server rendering, anything else maps to `en`. Without a locale it simply reports the current cookie value.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LocaleSyncController@sync",
                "x-source": "app/Http/Controllers/LocaleSyncController.php#L16-L41",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "locale": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Locale code (`ar` or `en`)."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ok: true, locale}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "locale": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sync/status/{id}": {
            "get": {
                "operationId": "get_api_sync_status_id",
                "tags": [
                    "Sync Jobs"
                ],
                "summary": "Sync job status",
                "description": "Progress of a sync job (`status`, `stage`, counts, `percentage`, `current_sku`, `last_error`, `stuck`). If the job is queued and no worker is running, one batch is processed inline.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "SyncJobController@status",
                "x-source": "app/Http/Controllers/SyncJobController.php#L62-L135",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SyncJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Job status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "status": {},
                                        "total_items": {
                                            "type": "integer"
                                        },
                                        "processed_items": {
                                            "type": "integer"
                                        },
                                        "success_items": {
                                            "type": "integer"
                                        },
                                        "failed_items": {
                                            "type": "integer"
                                        },
                                        "percentage": {
                                            "type": "integer"
                                        },
                                        "stage": {},
                                        "current_product_id": {},
                                        "current_sku": {},
                                        "last_error": {},
                                        "cancel_requested": {
                                            "type": "boolean"
                                        },
                                        "stuck": {},
                                        "worker_heartbeat_at": {
                                            "type": "string"
                                        },
                                        "started_at": {
                                            "type": "string"
                                        },
                                        "finished_at": {
                                            "type": "string"
                                        },
                                        "updated_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/sync/{id}/cancel": {
            "post": {
                "operationId": "post_api_sync_id_cancel",
                "tags": [
                    "Sync Jobs"
                ],
                "summary": "Cancel a sync job",
                "description": "Marks the job cancelled immediately; the worker stops at the next product boundary.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "SyncJobController@cancel",
                "x-source": "app/Http/Controllers/SyncJobController.php#L140-L154",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SyncJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/backups/{id}": {
            "delete": {
                "operationId": "delete_api_system_update_backups_id",
                "tags": [
                    "System Update"
                ],
                "summary": "Delete an update backup",
                "description": "Deletes one code/database backup created by the package updater. Rejected while an update is active.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@deleteBackup",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L299-L313",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Backup ID from the status object."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "409": {
                        "description": "Update in progress.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "An update is currently in progress."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Backup not found or cannot be deleted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/discard": {
            "post": {
                "operationId": "post_api_system_update_discard",
                "tags": [
                    "System Update"
                ],
                "summary": "Discard failed update state",
                "description": "Clears a finished or failed update state (and leaves maintenance mode) without restoring anything. Use after a successful rollback or when you have fixed the situation manually.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@discard",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L255-L266",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Cannot discard while steps are running.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/package": {
            "delete": {
                "operationId": "delete_api_system_update_package",
                "tags": [
                    "System Update"
                ],
                "summary": "Delete uploaded package",
                "description": "Removes the uploaded ZIP, partial chunks and metadata. Rejected while an update is active.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@deletePackage",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L269-L281",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Update in progress.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "An update is currently in progress."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/ping": {
            "get": {
                "operationId": "get_api_system_update_ping",
                "tags": [
                    "Health & Utilities"
                ],
                "summary": "Liveness probe during system update",
                "description": "Returns the literal string `pong`. Used by the System Update post-update health check; it is whitelisted from maintenance mode so it also answers while an update is running.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "SystemUpdateController@ping",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L49-L52",
                "x-middleware": [
                    "api"
                ],
                "responses": {
                    "200": {
                        "description": "Plain-text `pong`."
                    }
                },
                "security": []
            }
        },
        "/api/system-update/restore-backup": {
            "post": {
                "operationId": "post_api_system_update_restore_backup",
                "tags": [
                    "System Update"
                ],
                "summary": "Restore a backup",
                "description": "Starts restoring the given code + database backup (from the `backups` list in the status). Like updates, the restore proceeds via `step` calls.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@restoreBackup",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L285-L297",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Backup ID from `status.backups[].id`."
                                    }
                                },
                                "required": [
                                    "id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Another update/restore is active or the backup does not exist.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/resume": {
            "post": {
                "operationId": "post_api_system_update_resume",
                "tags": [
                    "System Update"
                ],
                "summary": "Resume paused update",
                "description": "Clears the error on a paused update so `step` can retry the failed step.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@resume",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L229-L240",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Nothing to resume.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/retention": {
            "post": {
                "operationId": "post_api_system_update_retention",
                "tags": [
                    "System Update"
                ],
                "summary": "Set backup retention",
                "description": "Sets how many update backups to keep (1–20) and immediately prunes older ones.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@saveRetention",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L315-L327",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "retention": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 20,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:1",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Number of most recent backups to keep."
                                    }
                                },
                                "required": [
                                    "retention"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/rollback": {
            "post": {
                "operationId": "post_api_system_update_rollback",
                "tags": [
                    "System Update"
                ],
                "summary": "Roll back current update",
                "description": "Requests a rollback of the active update to the backup taken at `start`. The rollback itself is performed by subsequent `step` calls.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@rollback",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L242-L253",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "No active update to roll back.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/start": {
            "post": {
                "operationId": "post_api_system_update_start",
                "tags": [
                    "System Update"
                ],
                "summary": "Start package update",
                "description": "Puts the updater into maintenance mode, snapshots code + database into a backup and initialises the step list. Nothing is deployed yet: call `POST /api/system-update/step` repeatedly until the status reports the update finished.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@start",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L198-L214",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object with `state.active = true`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Another update/restore is active.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Package not validated or validation failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "The package has not passed validation. Validate it before updating."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/status": {
            "get": {
                "operationId": "get_api_system_update_status",
                "tags": [
                    "System Update"
                ],
                "summary": "Get package-update status",
                "description": "Full state of the manual updater: uploaded package metadata (validated, version, report), current update state (phase, step index, log lines, started by/at), available backups and the retention setting. Every other `/api/system-update/*` endpoint returns this same object.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@status",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L41-L46",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{package: {...}|null, state: {active, phase, step, steps: [], log: [], error?}, backups: [{id, created_at, version, size}], retention}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/step": {
            "post": {
                "operationId": "post_api_system_update_step",
                "tags": [
                    "System Update"
                ],
                "summary": "Execute next update step",
                "description": "Runs the next pending step (extract, copy files, migrate, seed, clear caches, verify, finish). Each call is short so it survives web-server time limits; keep calling while `state.active` is true. A failing step stores the error and leaves the update paused so it can be resumed or rolled back.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@step",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L216-L227",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "No active update, or the current step is locked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/upload": {
            "post": {
                "operationId": "post_api_system_update_upload",
                "tags": [
                    "System Update"
                ],
                "summary": "Upload package chunk",
                "description": "Uploads one chunk of the release ZIP. Chunks must be sent in order (`index` 0..total-1) under a stable `upload_id`; an out-of-order chunk returns 409 with the expected index. When the last chunk arrives the parts are concatenated, the optional `sha256` is verified and the package metadata is written. Rejected while an update is active.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@uploadChunk",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L72-L171",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "chunk": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-laravel-rules": [
                                            "required",
                                            "file"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Binary chunk of the ZIP (recommended 1–5 MB)."
                                    },
                                    "filename": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Original ZIP filename (informational)."
                                    },
                                    "index": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Zero-based chunk index."
                                    },
                                    "sha256": {
                                        "type": "string",
                                        "minLength": 64,
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "size:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Hex SHA-256 of the complete ZIP; verified after the final chunk."
                                    },
                                    "total": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 20000,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:1",
                                            "max:20000"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Total number of chunks."
                                    },
                                    "upload_id": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Client-generated ID identifying this upload session."
                                    }
                                },
                                "required": [
                                    "chunk",
                                    "index",
                                    "total",
                                    "upload_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{received, total, complete}` — `complete` is true after the final chunk.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "received": {
                                            "type": "integer"
                                        },
                                        "total": {
                                            "type": "integer"
                                        },
                                        "complete": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Out-of-order chunk (`expected` gives the index to resend from) or an update is in progress.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Out-of-order upload chunk — please restart the upload."
                                        },
                                        "expected": {}
                                    }
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "Chunk exceeds the server upload limit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Upload chunk too large."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "500": {
                        "description": "Could not assemble the package on disk.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Could not finalize the uploaded package on disk."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system-update/validate": {
            "post": {
                "operationId": "post_api_system_update_validate",
                "tags": [
                    "System Update"
                ],
                "summary": "Validate uploaded package",
                "description": "Inspects the uploaded ZIP: manifest presence, version, required files, PHP version compatibility and checksums. The report is stored in the package metadata and `start` refuses to run until `ok` is true.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemUpdateController@validatePackage",
                "x-source": "app/Http/Controllers/SystemUpdateController.php#L175-L194",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update_settings",
                        "slug": "update_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status object; `package.report` contains `{ok, errors: [], warnings: [], package: {version, ...}}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No package uploaded yet.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "No uploaded package found — upload the update ZIP first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system_health": {
            "get": {
                "operationId": "get_api_system_health",
                "tags": [
                    "System Health"
                ],
                "summary": "Get system health metrics",
                "description": "Collects environment, PHP extensions, storage permissions, disk usage, database size, queue/cache drivers, scheduler last-run and pending migrations.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemHealthController@index",
                "x-source": "app/Http/Controllers/SystemHealthController.php#L15-L26",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "system_health_view",
                        "slug": "system_health_view",
                        "policy": "UserPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true, data: [{group, checks: [{label, value, status}]}], generated_at}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "generated_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/system_health/pdf": {
            "get": {
                "operationId": "get_api_system_health_pdf",
                "tags": [
                    "System Health"
                ],
                "summary": "Download system health PDF",
                "description": "Same metrics rendered as a PDF report with the company name and generation time.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SystemHealthController@pdf",
                "x-source": "app/Http/Controllers/SystemHealthController.php#L31-L55",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "system_health_view",
                        "slug": "system_health_view",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "x-response-type": "file",
                "responses": {
                    "200": {
                        "description": "PDF file (`application/pdf`).",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/task_change_status": {
            "post": {
                "operationId": "post_api_task_change_status",
                "tags": [
                    "Tasks"
                ],
                "summary": "Move a task to a status (by body id)",
                "description": "Sets the status; moving to `completed` sets progress to 100.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@task_change_status",
                "x-source": "app/Http/Controllers/TaskController.php#L337-L355",
                "x-route-name": "task_change_status",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-exists": "tasks,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "exists:tasks,id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Task id."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "not_started",
                                            "progress",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:not_started,progress,completed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target status."
                                    }
                                },
                                "required": [
                                    "id",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/tasks": {
            "get": {
                "operationId": "get_api_tasks",
                "tags": [
                    "Tasks"
                ],
                "summary": "List tasks",
                "description": "Paginated tasks with company / project names, per-status counters and the `companies` / `projects` lookups. `search` matches the title.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@index",
                "x-source": "app/Http/Controllers/TaskController.php#L21-L120",
                "x-route-name": "tasks.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "status",
                    "project_id",
                    "start_date",
                    "end_date",
                    "company_id"
                ],
                "x-models": [
                    "Task",
                    "Company",
                    "Project"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "company_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Company filter."
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact end date."
                    },
                    {
                        "name": "project_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Project filter."
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Exact start date."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter (LIKE) on status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`tasks[]`, `totalRows`, `companies[]`, `projects[]`, counters.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "tasks": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count_not_started": {},
                                        "count_in_progress": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count_cancelled": {},
                                        "count_completed": {},
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_tasks",
                "tags": [
                    "Tasks"
                ],
                "summary": "Create a task",
                "description": "Store a newly created resource in storage. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@store",
                "x-source": "app/Http/Controllers/TaskController.php#L146-L176",
                "x-route-name": "tasks.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "estimated_hour": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Estimated hours.",
                                        "type": "number"
                                    },
                                    "priority": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`low`, `medium`, `high`."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start date."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "`not_started`, `progress`, `completed`, `cancelled`."
                                    },
                                    "task_progress": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Progress 0–100 (default 0).",
                                        "type": "integer"
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title (max 255)."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "end_date",
                                    "project_id",
                                    "start_date",
                                    "status",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/tasks/create": {
            "get": {
                "operationId": "get_api_tasks_create",
                "tags": [
                    "Tasks"
                ],
                "summary": "Create-form data for a task",
                "description": "Show the form for creating a new resource. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@create",
                "x-source": "app/Http/Controllers/TaskController.php#L127-L139",
                "x-route-name": "tasks.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Project",
                    "Company"
                ],
                "responses": {
                    "200": {
                        "description": "`projects[]` and `companies[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/tasks/{task}": {
            "delete": {
                "operationId": "delete_api_tasks_task",
                "tags": [
                    "Tasks"
                ],
                "summary": "Delete a task",
                "description": "Remove the specified resource from storage. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@destroy",
                "x-source": "app/Http/Controllers/TaskController.php#L271-L281",
                "x-route-name": "tasks.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "parameters": [
                    {
                        "name": "task",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Task id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_tasks_task",
                "tags": [
                    "Tasks"
                ],
                "summary": "Get a task",
                "description": "The `task` with its `discussions` (with author) and `documents`.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@show",
                "x-source": "app/Http/Controllers/TaskController.php#L184-L198",
                "x-route-name": "tasks.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "parameters": [
                    {
                        "name": "task",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Task id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`task`, `discussions[]`, `documents[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "task": {},
                                        "discussions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "documents": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_tasks_task",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Tasks"
                ],
                "summary": "Update a task",
                "description": "Update the specified resource in storage. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@update",
                "x-source": "app/Http/Controllers/TaskController.php#L232-L263",
                "x-route-name": "tasks.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "parameters": [
                    {
                        "name": "task",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Task id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee ids (replaces the list).",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "estimated_hour": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Estimated hours.",
                                        "type": "number"
                                    },
                                    "priority": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Priority."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "task_progress": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Progress 0–100.",
                                        "type": "integer"
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "end_date",
                                    "project_id",
                                    "start_date",
                                    "status",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_tasks_task",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Tasks"
                ],
                "summary": "Update a task",
                "description": "Update the specified resource in storage. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@update",
                "x-source": "app/Http/Controllers/TaskController.php#L232-L263",
                "x-route-name": "tasks.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "parameters": [
                    {
                        "name": "task",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Task id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee ids (replaces the list).",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "company_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Company."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Due date."
                                    },
                                    "estimated_hour": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Estimated hours.",
                                        "type": "number"
                                    },
                                    "priority": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Priority."
                                    },
                                    "project_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Project."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start."
                                    },
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Status."
                                    },
                                    "task_progress": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Progress 0–100.",
                                        "type": "integer"
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Title."
                                    }
                                },
                                "required": [
                                    "company_id",
                                    "end_date",
                                    "project_id",
                                    "start_date",
                                    "status",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/tasks/{task}/edit": {
            "get": {
                "operationId": "get_api_tasks_task_edit",
                "tags": [
                    "Tasks"
                ],
                "summary": "Edit-form data for a task",
                "description": "Show the form for editing the specified resource. /",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@edit",
                "x-source": "app/Http/Controllers/TaskController.php#L206-L224",
                "x-route-name": "tasks.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task",
                    "EmployeeTask",
                    "Project",
                    "Company",
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "task",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Task id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`task`, `assigned_employees[]`, `projects[]`, `companies[]`, `employees[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "task": {},
                                        "assigned_employees": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "projects": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "companies": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "employees": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/tasks_kanban": {
            "get": {
                "operationId": "get_api_tasks_kanban",
                "tags": [
                    "Tasks"
                ],
                "summary": "Task board (kanban)",
                "description": "All open tasks grouped in `columns` keyed by status (`not_started`, `progress`, `completed`, `cancelled`), each card with `progress`, `priority`, `project_title` and `is_overdue`; plus `total` and `overdue` counts.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@tasks_kanban",
                "x-source": "app/Http/Controllers/TaskController.php#L291-L334",
                "x-route-name": "tasks_kanban",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "parameters": [
                    {
                        "name": "priority",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Priority filter."
                    },
                    {
                        "name": "project_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Project filter."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Title search."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`columns`, `total`, `overdue`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "title": {},
                                        "project_id": {},
                                        "project_title": {},
                                        "start_date": {},
                                        "end_date": {},
                                        "status": {},
                                        "priority": {},
                                        "progress": {
                                            "type": "integer"
                                        },
                                        "estimated_hour": {
                                            "nullable": true,
                                            "type": "string"
                                        },
                                        "is_overdue": {},
                                        "columns": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total": {
                                            "type": "integer"
                                        },
                                        "overdue": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/telegram/settings": {
            "get": {
                "operationId": "get_api_telegram_settings",
                "tags": [
                    "Telegram"
                ],
                "summary": "Get Telegram settings",
                "description": "Telegram integration settings: bot token (masked), chat ID, enabled events.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\TelegramSettingsController@show",
                "x-source": "app/Http/Controllers/Integrations/TelegramSettingsController.php#L19-L33",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "TelegramSettingPolicy"
                    }
                ],
                "x-models": [
                    "TelegramSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `configured`, `bot_token_hint`, `chat_id`, `events[]`, `available_events[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "configured": {},
                                        "bot_token_hint": {
                                            "type": "string"
                                        },
                                        "chat_id": {},
                                        "events": {},
                                        "available_events": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_telegram_settings",
                "tags": [
                    "Telegram"
                ],
                "summary": "Save Telegram settings",
                "description": "Saves the bot token, chat ID and which events to notify.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\TelegramSettingsController@update",
                "x-source": "app/Http/Controllers/Integrations/TelegramSettingsController.php#L35-L65",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "TelegramSettingPolicy"
                    }
                ],
                "x-models": [
                    "TelegramSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "bot_token": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Bot token (write-only)."
                                    },
                                    "chat_id": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target chat id."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "events": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Events to forward.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `configured`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "configured": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/telegram/settings/test": {
            "post": {
                "operationId": "post_api_telegram_settings_test",
                "tags": [
                    "Telegram"
                ],
                "summary": "Send a Telegram test message",
                "description": "Sends a test message through the configured bot and reports the result.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\TelegramSettingsController@test",
                "x-source": "app/Http/Controllers/Integrations/TelegramSettingsController.php#L67-L81",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "TelegramSettingPolicy"
                    }
                ],
                "x-models": [
                    "TelegramSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {},
                                        "error": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not configured or send failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Add the bot token and chat id first."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/test_config_mail": {
            "post": {
                "operationId": "post_api_test_config_mail",
                "tags": [
                    "Mail Settings"
                ],
                "summary": "Send a test email",
                "description": "Loads the stored mail config and sends a test message. Recipient precedence: `email` in the body, then the current user's email, then the company email.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "MailSettingsController@test_config_mail",
                "x-source": "app/Http/Controllers/MailSettingsController.php#L50-L92",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "mail_settings",
                        "slug": "mail_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting",
                    "Server"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Recipient address for the test."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true, message, data}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "nullable": true,
                                            "type": "string"
                                        }
                                    },
                                    "x-envelope": "sendResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "No recipient available, or the mailer threw (message in `message`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "errors": {}
                                    },
                                    "x-envelope": "sendError"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/today_summary": {
            "get": {
                "operationId": "get_api_today_summary",
                "tags": [
                    "Dashboard"
                ],
                "summary": "Get today's summary",
                "description": "Data for the top-bar *Today's summary* drawer: today's sales/purchases/returns counts and totals, payments in/out, expenses, stock alerts, new customers and a gross-profit estimate, plus the KPI tiles. Warehouse and record_view restrictions apply wherever the underlying row supports them; stock levels and new customers stay global.",
                "x-section": "Dashboard & Reports",
                "x-surface": "admin",
                "x-controller": "TodaySummaryController@index",
                "x-source": "app/Http/Controllers/TodaySummaryController.php#L24-L285",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "UserWarehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`{date, sales: {count, total, paid, due}, purchases: {...}, stock: {alerts, value}, payments: {in, out}, profit, tiles: {...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "date": {},
                                        "sales": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "purchases": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "stock": {},
                                        "payments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "profit": {},
                                        "tiles": {
                                            "type": "object",
                                            "properties": {
                                                "new_customers": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "low_stock": {},
                                                "on_shift": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/transfer_money": {
            "get": {
                "operationId": "get_api_transfer_money",
                "tags": [
                    "Money Transfers"
                ],
                "summary": "List money transfers",
                "description": "Paginated transfers: `id, from_account, to_account, from_account_id, to_account_id, amount, date`. `search` matches either account name. Also returns `accounts`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "TransferMoneyController@index",
                "x-source": "app/Http/Controllers/TransferMoneyController.php#L14-L74",
                "x-route-name": "transfer_money.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "transfer_money",
                        "policy": "TransferMoneyPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "TransferMoney",
                    "Account"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`transfers[]`, `accounts[]`, `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "transfers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "accounts": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_transfer_money",
                "tags": [
                    "Money Transfers"
                ],
                "summary": "Create a money transfer",
                "description": "Moves `amount` from one account to another: the source balance must cover the amount (`400` otherwise) and the two accounts must differ.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "TransferMoneyController@store",
                "x-source": "app/Http/Controllers/TransferMoneyController.php#L78-L127",
                "x-route-name": "transfer_money.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "transfer_money",
                        "policy": "TransferMoneyPolicy"
                    }
                ],
                "x-models": [
                    "Account",
                    "TransferMoney"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Amount to move."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Transfer date."
                                    },
                                    "from_account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-rules": [
                                            "different:to_account_id"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "different:to_account_id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Source account id."
                                    },
                                    "to_account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-rules": [
                                            "different:from_account_id"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "different:from_account_id"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Destination account id (different from source)."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "date",
                                    "from_account_id",
                                    "to_account_id"
                                ]
                            },
                            "example": {
                                "from_account_id": 1,
                                "to_account_id": 2,
                                "amount": 300,
                                "date": "2026-09-06"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Same accounts or insufficient balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient balance in the from account."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/transfer_money/{transfer_money}": {
            "delete": {
                "operationId": "delete_api_transfer_money_transfer_money",
                "tags": [
                    "Money Transfers"
                ],
                "summary": "Delete a money transfer",
                "description": "Soft-deletes the transfer and moves the amount back to the source account.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "TransferMoneyController@destroy",
                "x-source": "app/Http/Controllers/TransferMoneyController.php#L187-L214",
                "x-route-name": "transfer_money.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "transfer_money",
                        "policy": "TransferMoneyPolicy"
                    }
                ],
                "x-models": [
                    "TransferMoney",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "transfer_money",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_transfer_money_transfer_money",
                "tags": [
                    "Money Transfers"
                ],
                "summary": "(Not implemented) Get a money transfer",
                "description": "Empty stub; returns an empty `200`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "TransferMoneyController@show",
                "x-source": "app/Http/Controllers/TransferMoneyController.php#L131-L135",
                "x-route-name": "transfer_money.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "transfer_money",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_transfer_money_transfer_money",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Money Transfers"
                ],
                "summary": "Update a money transfer",
                "description": "Changes the amount and date of an existing transfer (accounts cannot be changed) and re-balances both accounts; the source must still cover the new amount.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "TransferMoneyController@update",
                "x-source": "app/Http/Controllers/TransferMoneyController.php#L139-L183",
                "x-route-name": "transfer_money.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "transfer_money",
                        "policy": "TransferMoneyPolicy"
                    }
                ],
                "x-models": [
                    "TransferMoney",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "transfer_money",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New date."
                                    },
                                    "from_account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Source account id."
                                    },
                                    "to_account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Destination account id (different from source)."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "date"
                                ]
                            },
                            "example": {
                                "from_account_id": 1,
                                "to_account_id": 2,
                                "amount": 300,
                                "date": "2026-09-06"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Insufficient balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient balance in the from account."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_transfer_money_transfer_money",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Money Transfers"
                ],
                "summary": "Update a money transfer",
                "description": "Changes the amount and date of an existing transfer (accounts cannot be changed) and re-balances both accounts; the source must still cover the new amount.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "TransferMoneyController@update",
                "x-source": "app/Http/Controllers/TransferMoneyController.php#L139-L183",
                "x-route-name": "transfer_money.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "transfer_money",
                        "policy": "TransferMoneyPolicy"
                    }
                ],
                "x-models": [
                    "TransferMoney",
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "transfer_money",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New amount."
                                    },
                                    "date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New date."
                                    },
                                    "from_account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Source account id."
                                    },
                                    "to_account_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Destination account id (different from source)."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "date"
                                ]
                            },
                            "example": {
                                "from_account_id": 1,
                                "to_account_id": 2,
                                "amount": 300,
                                "date": "2026-09-06"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Insufficient balance.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient balance in the from account."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/transfer_pdf/{id}": {
            "get": {
                "operationId": "get_api_transfer_pdf_id",
                "tags": [
                    "Public PDF & Print"
                ],
                "summary": "Stock transfer PDF",
                "description": "Transfer note with source/destination warehouse, status and line items (with batches).",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "TransferController@transfer_pdf",
                "x-source": "app/Http/Controllers/TransferController.php#L1366-L1438",
                "x-middleware": [
                    "api"
                ],
                "x-models": [
                    "Transfer",
                    "Unit",
                    "Product",
                    "ProductVariant",
                    "Setting"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Transfer ID."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/transfers": {
            "get": {
                "operationId": "get_api_transfers",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "List stock transfers",
                "description": "Paginated transfers where the source **or** destination is one of the caller's warehouses. Rows: `id, date, Ref, from_warehouse, to_warehouse, GrandTotal, items, statut, approval_status`. `search` matches `Ref`, `statut` and warehouse names. Also returns `warehouses`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@index",
                "x-source": "app/Http/Controllers/TransferController.php#L29-L132",
                "x-route-name": "transfers.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "transfer_view",
                        "policy": "TransferPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "Ref",
                    "from_warehouse_id",
                    "to_warehouse_id",
                    "statut"
                ],
                "x-models": [
                    "UserWarehouse",
                    "Transfer",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "Ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on reference."
                    },
                    {
                        "name": "from_warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Source warehouse."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "filter"
                            ],
                            "type": "string"
                        },
                        "description": "`completed`, `sent` or `pending`."
                    },
                    {
                        "name": "to_warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Destination warehouse."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`transfers[]`, `totalRows`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "transfers": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_transfers",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Create a stock transfer",
                "description": "Creates a transfer with `approval_status = pending`; **no stock moves** until `POST /api/transfers/{id}/approve`. Header fields live under the `transfer` object, lines under `details`. Line quantities are in the line's `purchase_unit_id` and converted to base units with the unit operator.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@store",
                "x-source": "app/Http/Controllers/TransferController.php#L136-L312",
                "x-route-name": "transfers.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "transfer_add",
                        "policy": "TransferPolicy"
                    }
                ],
                "x-models": [
                    "Transfer",
                    "Unit",
                    "product_warehouse",
                    "TransferDetail"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document total (computed client-side).",
                                        "type": "number"
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Lines: `{product_id, product_variant_id, quantity, purchase_unit_id, cost/Net_price, tax_percent, tax_method, discount, discount_Method, subtotal, batches?}`.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "transfer": {
                                        "x-inferred": true,
                                        "type": "object",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Header object.",
                                        "properties": {
                                            "from_warehouse": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Source warehouse id. Required."
                                            },
                                            "to_warehouse": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Destination warehouse id. Required."
                                            }
                                        },
                                        "required": [
                                            "from_warehouse",
                                            "to_warehouse"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "transfer": {
                                    "from_warehouse": 1,
                                    "to_warehouse": 2,
                                    "date": "2026-09-06",
                                    "statut": "completed",
                                    "tax_rate": 0,
                                    "TaxNet": 0,
                                    "discount": 0,
                                    "shipping": 0,
                                    "notes": "Restock north depot"
                                },
                                "GrandTotal": 250,
                                "details": [
                                    {
                                        "product_id": 5,
                                        "product_variant_id": null,
                                        "quantity": 10,
                                        "purchase_unit_id": 1,
                                        "cost": 25,
                                        "tax_percent": 0,
                                        "tax_method": "1",
                                        "discount": 0,
                                        "discount_Method": "2",
                                        "subtotal": 250
                                    }
                                ]
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/transfers/create": {
            "get": {
                "operationId": "get_api_transfers_create",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Get lookups for the transfer form",
                "description": "`warehouses` the caller may transfer **from** (their assigned ones) and `to_warehouses` (all warehouses).",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@create",
                "x-source": "app/Http/Controllers/TransferController.php#L1346-L1362",
                "x-route-name": "transfers.create",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "transfer_add",
                        "policy": "TransferPolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "UserWarehouse"
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]`, `to_warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "to_warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/transfers/delete/by_selection": {
            "post": {
                "operationId": "post_api_transfers_delete_by_selection",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Delete several transfers",
                "description": "Deletes every transfer in `selectedIds`, reversing stock for approved ones.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@delete_by_selection",
                "x-source": "app/Http/Controllers/TransferController.php#L816-L972",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "transfer_delete",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer",
                    "TransferDetail",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of transfer ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/transfers/{id}/approve": {
            "post": {
                "operationId": "post_api_transfers_id_approve",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Approve a pending transfer",
                "description": "Sets `approval_status = approved` and applies the stock movement **once** according to the stored `statut` (`completed`: minus source / plus destination; `sent`: minus source only). Already approved transfers are a no-op; rejected ones return `422`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@approve",
                "x-source": "app/Http/Controllers/TransferController.php#L1445-L1484",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "transfer_edit",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Transfer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Rejected transfers cannot be approved without editing."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/transfers/{id}/reject": {
            "post": {
                "operationId": "post_api_transfers_id_reject",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Reject a pending transfer",
                "description": "Sets `approval_status = rejected`; no stock ever moves. Approved transfers cannot be rejected (`422`) — delete or edit them instead.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@reject",
                "x-source": "app/Http/Controllers/TransferController.php#L1489-L1518",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "transfer_edit",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Transfer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Transfer already approved."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/transfers/{transfer}": {
            "delete": {
                "operationId": "delete_api_transfers_transfer",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Delete a stock transfer",
                "description": "Soft-deletes the transfer. If it was approved, its stock movement (and batch movements) is reversed first.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@destroy",
                "x-source": "app/Http/Controllers/TransferController.php#L662-L812",
                "x-route-name": "transfers.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "transfer_delete",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer",
                    "TransferDetail",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "transfer",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_transfers_transfer",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Get a stock transfer",
                "description": "Read-only view: `transfer` header (`id, date, note, Ref, from_warehouse, to_warehouse, items, statut, approval_status, GrandTotal`) and `details[]` (`code, name, quantity, unit, total, is_batch_tracked, batches[]`).",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@show",
                "x-source": "app/Http/Controllers/TransferController.php#L1268-L1342",
                "x-route-name": "transfers.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "transfer_view",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer",
                    "Unit",
                    "Product",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "transfer",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`transfer` and `details[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "transfer": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_transfers_transfer",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Update a stock transfer",
                "description": "Same payload as create. If the transfer is already **approved**, the old stock movement is reversed and the new one applied according to the new `statut`; pending or rejected transfers are edited without touching stock.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@update",
                "x-source": "app/Http/Controllers/TransferController.php#L316-L658",
                "x-route-name": "transfers.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "transfer_edit",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer",
                    "TransferDetail",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "transfer",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer header as a nested object: `date`, `from_warehouse`, `to_warehouse`, `statut` (`completed`, `pending`, `sent`), `tax_rate`, `discount`, `shipping`, `notes`. Lines are sent in `details`."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document total.",
                                        "type": "number"
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing ones).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "transfer": {
                                        "properties": {
                                            "from_warehouse": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Source warehouse ID."
                                            },
                                            "to_warehouse": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Destination warehouse ID."
                                            }
                                        },
                                        "required": [
                                            "from_warehouse",
                                            "to_warehouse"
                                        ],
                                        "description": "Transfer header as a nested object: `date`, `from_warehouse`, `to_warehouse`, `statut` (`completed`, `pending`, `sent`), `tax_rate`, `discount`, `shipping`, `notes`. Lines are sent in `details`.",
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_transfers_transfer",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Update a stock transfer",
                "description": "Same payload as create. If the transfer is already **approved**, the old stock movement is reversed and the new one applied according to the new `statut`; pending or rejected transfers are edited without touching stock.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@update",
                "x-source": "app/Http/Controllers/TransferController.php#L316-L658",
                "x-route-name": "transfers.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "transfer_edit",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer",
                    "TransferDetail",
                    "Unit",
                    "Product",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "transfer",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer header as a nested object: `date`, `from_warehouse`, `to_warehouse`, `statut` (`completed`, `pending`, `sent`), `tax_rate`, `discount`, `shipping`, `notes`. Lines are sent in `details`."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "GrandTotal": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Document total.",
                                        "type": "number"
                                    },
                                    "details": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Full list of lines (`id` for existing ones).",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "transfer": {
                                        "properties": {
                                            "from_warehouse": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Source warehouse ID."
                                            },
                                            "to_warehouse": {
                                                "x-inferred": true,
                                                "type": "string",
                                                "x-laravel-rules": [
                                                    "required"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Destination warehouse ID."
                                            }
                                        },
                                        "required": [
                                            "from_warehouse",
                                            "to_warehouse"
                                        ],
                                        "description": "Transfer header as a nested object: `date`, `from_warehouse`, `to_warehouse`, `statut` (`completed`, `pending`, `sent`), `tax_rate`, `discount`, `shipping`, `notes`. Lines are sent in `details`.",
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/transfers/{transfer}/edit": {
            "get": {
                "operationId": "get_api_transfers_transfer_edit",
                "tags": [
                    "Stock Transfers"
                ],
                "summary": "Get a transfer for editing",
                "description": "Form-shaped payload: `transfer` (`from_warehouse, to_warehouse, date, statut, tax_rate, TaxNet, discount, shipping, notes`), `details[]` lines (`id, detail_id, product_id, product_variant_id, code, name, quantity, purchase_unit_id, unit, cost, current, subtotal, batches`) and both warehouse lists. Accessible if either warehouse belongs to the caller.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "TransferController@edit",
                "x-source": "app/Http/Controllers/TransferController.php#L1032-L1264",
                "x-route-name": "transfers.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "transfer_edit",
                        "policy": "TransferPolicy"
                    },
                    {
                        "ability": "check_record",
                        "slug": "check_record"
                    }
                ],
                "x-models": [
                    "Transfer",
                    "UserWarehouse",
                    "Warehouse",
                    "Unit",
                    "Product",
                    "product_warehouse",
                    "ProductVariant"
                ],
                "parameters": [
                    {
                        "name": "transfer",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Transfer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`transfer`, `details[]`, `warehouses[]`, `to_warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product_batch_id": {},
                                        "batch_no": {},
                                        "expiry_date": {},
                                        "qty_available": {
                                            "type": "integer",
                                            "example": 0
                                        },
                                        "qty": {},
                                        "details": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "transfer": {},
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "to_warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Neither warehouse is assigned to the caller.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You are not allowed to access this transfer (warehouse restriction)."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/translations/{locale}": {
            "get": {
                "operationId": "get_api_translations_locale",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Get UI translations for a locale",
                "description": "Returns the full translation catalogue for one locale as a flat `key → value` object, read from the `translations` table (editable in System Settings → Languages). Unknown locales return an empty object.",
                "x-section": "Authentication & Public",
                "x-surface": "public",
                "x-public": true,
                "x-middleware": [
                    "api"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "en"
                        },
                        "description": "Locale code such as `en`, `fr`, `ar`, `es`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Flat object of translation keys to translated strings."
                    }
                },
                "security": []
            }
        },
        "/api/translations_setting/{locale}": {
            "get": {
                "operationId": "get_api_translations_setting_locale",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "List translations for editing",
                "description": "Paginated editor view of a locale: iterates over every English key (the master list), returns the English value alongside the target locale's value (or `null` when missing) and supports searching keys and values. Also returns the language record.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@get_translate",
                "x-source": "app/Http/Controllers/LanguageController.php#L195-L264",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Translate",
                    "Language"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "en"
                        },
                        "description": "Target locale code."
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Page number (default 1)."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Rows per page (default 100)."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on key or English value."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{data: [{key, en_value, value, id}], total, per_page, current_page, language}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "key": {},
                                        "value": {},
                                        "locale": {},
                                        "id": {},
                                        "data": {},
                                        "total": {
                                            "type": "integer"
                                        },
                                        "per_page": {
                                            "type": "integer"
                                        },
                                        "current_page": {
                                            "type": "integer"
                                        },
                                        "language": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_translations_setting_locale",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Save a translation",
                "description": "Creates or updates one key for the locale and flags it `is_customized` so the translation seeder never overwrites it on update.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@updateOrInsert",
                "x-source": "app/Http/Controllers/LanguageController.php#L266-L285",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Translate"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "en"
                        },
                        "description": "Locale code."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "key": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Translation key (max 255)."
                                    },
                                    "value": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Translated text (null to clear)."
                                    }
                                },
                                "required": [
                                    "key"
                                ]
                            },
                            "example": {
                                "key": "Dashboard",
                                "value": "Tableau de bord"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{message, data: translation}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Translation saved successfully."
                                        },
                                        "data": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/translations_setting/{locale}/{key}": {
            "delete": {
                "operationId": "delete_api_translations_setting_locale_key",
                "tags": [
                    "Languages & Translations"
                ],
                "summary": "Delete a translation key",
                "description": "Removes a custom key from a locale. Keys shipped with Stocky (`is_default`) cannot be deleted; clear their value instead.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "LanguageController@delete_translate",
                "x-source": "app/Http/Controllers/LanguageController.php#L287-L315",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "translations_settings",
                        "slug": "translations_settings",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Translate"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "en"
                        },
                        "description": "Locale code."
                    },
                    {
                        "name": "key",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Translation key."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{message}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Translation deleted successfully."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Attempted to delete a built-in key.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "You cannot delete a default/original translation key."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/trays": {
            "get": {
                "operationId": "get_api_trays",
                "tags": [
                    "Trays"
                ],
                "summary": "List trays",
                "description": "Paginated trays; `search` matches name or description.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "TraysController@index",
                "x-source": "app/Http/Controllers/TraysController.php#L13-L45",
                "x-route-name": "trays.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "TrayPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Tray"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`trays[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "trays": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_trays",
                "tags": [
                    "Trays"
                ],
                "summary": "Create a tray",
                "description": "Creates a tray / table. Returns HTTP **201** with the row.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "TraysController@store",
                "x-source": "app/Http/Controllers/TraysController.php#L49-L66",
                "x-route-name": "trays.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "policy": "TrayPolicy"
                    }
                ],
                "x-models": [
                    "Tray"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tray name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and `tray`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "tray": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/trays/delete/by_selection": {
            "post": {
                "operationId": "post_api_trays_delete_by_selection",
                "tags": [
                    "Trays"
                ],
                "summary": "Delete several trays",
                "description": "Soft-deletes each tray in `selectedIds`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "TraysController@delete_by_selection",
                "x-source": "app/Http/Controllers/TraysController.php#L108-L120",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "TrayPolicy"
                    }
                ],
                "x-models": [
                    "Tray"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of tray ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/trays/{tray}": {
            "delete": {
                "operationId": "delete_api_trays_tray",
                "tags": [
                    "Trays"
                ],
                "summary": "Delete a tray",
                "description": "Soft-deletes the tray.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "TraysController@destroy",
                "x-source": "app/Http/Controllers/TraysController.php#L95-L104",
                "x-route-name": "trays.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "policy": "TrayPolicy"
                    }
                ],
                "x-models": [
                    "Tray"
                ],
                "parameters": [
                    {
                        "name": "tray",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Tray id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_trays_tray",
                "tags": [
                    "Trays"
                ],
                "summary": "(Not implemented) Get a tray",
                "description": "Empty stub; returns an empty `200`.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "TraysController@show",
                "x-source": "app/Http/Controllers/TraysController.php#L70-L73",
                "x-route-name": "trays.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "tray",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Tray id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_trays_tray",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Trays"
                ],
                "summary": "Update a tray",
                "description": "Updates name and description.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "TraysController@update",
                "x-source": "app/Http/Controllers/TraysController.php#L77-L91",
                "x-route-name": "trays.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "TrayPolicy"
                    }
                ],
                "x-models": [
                    "Tray"
                ],
                "parameters": [
                    {
                        "name": "tray",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Tray id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_trays_tray",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Trays"
                ],
                "summary": "Update a tray",
                "description": "Updates name and description.",
                "x-section": "Point of Sale",
                "x-surface": "admin",
                "x-controller": "TraysController@update",
                "x-source": "app/Http/Controllers/TraysController.php#L77-L91",
                "x-route-name": "trays.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "TrayPolicy"
                    }
                ],
                "x-models": [
                    "Tray"
                ],
                "parameters": [
                    {
                        "name": "tray",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Tray id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/units": {
            "get": {
                "operationId": "get_api_units",
                "tags": [
                    "Units"
                ],
                "summary": "List units",
                "description": "Paginated units. Each row: `id, name, ShortName, operator, operator_value, base_unit (id or empty), base_unit_name`. `search` matches name or short name. `Units_base` lists the base units (for the *base unit* dropdown).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@index",
                "x-source": "app/Http/Controllers/UnitsController.php#L14-L74",
                "x-route-name": "units.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "unit",
                        "policy": "UnitPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Unit"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`Units[]`, `Units_base[]`, `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "Units": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "Units_base": {},
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "Units": [
                                        {
                                            "id": 1,
                                            "name": "Piece",
                                            "ShortName": "Pc",
                                            "operator": "*",
                                            "operator_value": 1,
                                            "base_unit": "",
                                            "base_unit_name": ""
                                        },
                                        {
                                            "id": 2,
                                            "name": "Box of 12",
                                            "ShortName": "Box",
                                            "operator": "*",
                                            "operator_value": 12,
                                            "base_unit": 1,
                                            "base_unit_name": "Piece"
                                        }
                                    ],
                                    "Units_base": [
                                        {
                                            "id": 1,
                                            "name": "Piece"
                                        }
                                    ],
                                    "totalRows": 2
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_units",
                "tags": [
                    "Units"
                ],
                "summary": "Create a unit",
                "description": "Creates a base unit (no `base_unit`; operator forced to `*` and value `1`) or a sub-unit converting to its base unit: `operator` `*` means *1 sub-unit = operator_value base units* (Box of 12 → `*`, `12`); `/` means *1 sub-unit = 1/operator_value base unit* (Gram of Kg → `/`, `1000`). Returns the created `unit` so a form can select it immediately.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@store",
                "x-source": "app/Http/Controllers/UnitsController.php#L78-L106",
                "x-route-name": "units.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "unit",
                        "policy": "UnitPolicy"
                    }
                ],
                "x-models": [
                    "Unit"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ShortName": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Abbreviation printed on documents."
                                    },
                                    "base_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Id of the base unit, or empty for a base unit."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unit name."
                                    },
                                    "operator": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`*` or `/` (sub-units only)."
                                    },
                                    "operator_value": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Conversion factor (sub-units only)."
                                    }
                                },
                                "required": [
                                    "ShortName",
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Box of 12",
                                "ShortName": "Box",
                                "base_unit": 1,
                                "operator": "*",
                                "operator_value": 12
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the created `unit`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "unit": {}
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "unit": {
                                        "id": 2,
                                        "name": "Box of 12",
                                        "ShortName": "Box",
                                        "base_unit": 1,
                                        "operator": "*",
                                        "operator_value": 12
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/units/delete/by_selection": {
            "post": {
                "operationId": "post_api_units_delete_by_selection",
                "tags": [
                    "Units"
                ],
                "summary": "Delete several units",
                "description": "Soft-deletes the selected units. Deleting a base unit together with all its sub-units is allowed; if any sub-unit **outside** the selection still uses a selected base unit, nothing is deleted and `422` lists the blocking units.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@delete_by_selection",
                "x-source": "app/Http/Controllers/UnitsController.php#L167-L201",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "unit",
                        "policy": "UnitPolicy"
                    }
                ],
                "x-models": [
                    "Unit"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer",
                                            "x-laravel-rules": [
                                                "integer"
                                            ]
                                        },
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Array of unit ids."
                                    }
                                },
                                "required": [
                                    "selectedIds"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/units/{unit}": {
            "delete": {
                "operationId": "delete_api_units_unit",
                "tags": [
                    "Units"
                ],
                "summary": "Delete a unit",
                "description": "Soft-deletes the unit unless other sub-units still use it as their base (then `422`).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@destroy",
                "x-source": "app/Http/Controllers/UnitsController.php#L143-L163",
                "x-route-name": "units.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "unit",
                        "policy": "UnitPolicy"
                    }
                ],
                "x-models": [
                    "Unit"
                ],
                "parameters": [
                    {
                        "name": "unit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Unit id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "`success: false` – sub-units still reference this base unit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "This unit cannot be deleted while sub-units still use it."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_units_unit",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Units"
                ],
                "summary": "Update a unit",
                "description": "Updates the unit. Sending an empty `base_unit`, or the unit's own id, turns it into a base unit (`operator *`, value `1`).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@update",
                "x-source": "app/Http/Controllers/UnitsController.php#L110-L139",
                "x-route-name": "units.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "unit",
                        "policy": "UnitPolicy"
                    }
                ],
                "x-models": [
                    "Unit"
                ],
                "parameters": [
                    {
                        "name": "unit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Unit id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ShortName": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Abbreviation."
                                    },
                                    "base_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Base unit id or empty."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unit name."
                                    },
                                    "operator": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`*` or `/`."
                                    },
                                    "operator_value": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Conversion factor."
                                    }
                                },
                                "required": [
                                    "ShortName",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_units_unit",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Units"
                ],
                "summary": "Update a unit",
                "description": "Updates the unit. Sending an empty `base_unit`, or the unit's own id, turns it into a base unit (`operator *`, value `1`).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "UnitsController@update",
                "x-source": "app/Http/Controllers/UnitsController.php#L110-L139",
                "x-route-name": "units.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "unit",
                        "policy": "UnitPolicy"
                    }
                ],
                "x-models": [
                    "Unit"
                ],
                "parameters": [
                    {
                        "name": "unit",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Unit id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ShortName": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Abbreviation."
                                    },
                                    "base_unit": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Base unit id or empty."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Unit name."
                                    },
                                    "operator": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`*` or `/`."
                                    },
                                    "operator_value": {
                                        "x-inferred": true,
                                        "type": "number",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Conversion factor."
                                    }
                                },
                                "required": [
                                    "ShortName",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/update-customer-stripe": {
            "post": {
                "operationId": "post_api_update_customer_stripe",
                "tags": [
                    "Stripe"
                ],
                "summary": "Update default card (deprecated)",
                "description": "No-op kept for backward compatibility.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "StripeController@updateCustomer",
                "x-source": "app/Http/Controllers/StripeController.php#L35-L38",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update/preflight": {
            "get": {
                "operationId": "get_api_update_preflight",
                "tags": [
                    "System Update"
                ],
                "summary": "Update preflight checks",
                "description": "Checks everything the one-click updater needs: `DUMP_PATH`/`MYSQL_PATH` tool paths, writability of base, storage, bootstrap/cache and public directories, outbound network to the update server and free disk space. `ok` is true only when every check passes.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "AutoUpdateController@preflight",
                "x-source": "app/Http/Controllers/AutoUpdateController.php#L1026-L1069",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`{ok, tools: {DUMP_PATH, MYSQL_PATH}, permissions: {base, storage, ...}, network, disk: {free, required}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "tools": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "permissions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "network": {},
                                        "disk": {
                                            "type": "object",
                                            "properties": {
                                                "base_free": {},
                                                "storage_free": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update/progress": {
            "get": {
                "operationId": "get_api_update_progress",
                "tags": [
                    "System Update"
                ],
                "summary": "Get one-click update progress",
                "description": "Returns the current step and percentage of a running one-click update, or `{step: \"idle\", percent: 0}` when none is active. Poll every few seconds while `POST /api/one_click_update` is in flight.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "AutoUpdateController@progress",
                "x-source": "app/Http/Controllers/AutoUpdateController.php#L997-L1007",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "`{step, percent, message?}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "step": {
                                            "type": "string",
                                            "example": "idle"
                                        },
                                        "percent": {
                                            "type": "integer",
                                            "example": 0
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_Default_SMS": {
            "put": {
                "operationId": "put_api_update_Default_SMS",
                "tags": [
                    "SMS Settings"
                ],
                "summary": "Set default SMS gateway",
                "description": "Stores the gateway name used for notifications. Send the string `null` to disable SMS. Returns an empty 200 body.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Sms_SettingsController@update_Default_SMS",
                "x-source": "app/Http/Controllers/Sms_SettingsController.php#L190-L205",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "sms_settings",
                        "slug": "sms_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "default_sms_gateway": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`twilio`, `termi`, `infobip`, `custom` or `null`."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_appearance_settings/{id}": {
            "put": {
                "operationId": "put_api_update_appearance_settings_id",
                "tags": [
                    "System Settings"
                ],
                "summary": "Update appearance settings",
                "description": "Saves branding and login-page copy. `logo` and `favicon` are optional uploads stored under `public/images`; the previous files are removed when replaced. `login_bg_color` must be a 3- or 6-digit hex colour, otherwise the override is cleared. Send as multipart (use `POST` with `_method=PUT` if your client cannot send multipart PUT).",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@update_appearance_settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L1910-L1988",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "appearance_settings",
                        "slug": "appearance_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "ID of the settings row."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "app_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Application name shown in the sidebar, browser title and PWA manifest."
                                    },
                                    "customize_button_visible": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Show the theme customiser button in the top bar."
                                    },
                                    "developed_by": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Credit line in the footer."
                                    },
                                    "favicon": {
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Favicon image upload (PNG/ICO).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "footer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Footer text."
                                    },
                                    "hide_site_name": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hide the app name next to the logo.",
                                        "type": "boolean"
                                    },
                                    "login_bg_color": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Hex background colour of the login page (`#RRGGBB`)."
                                    },
                                    "login_btn_text": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Label of the sign-in button."
                                    },
                                    "login_footer_text": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Footer text under the login form."
                                    },
                                    "login_hero_badge": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Small badge text above the login hero title."
                                    },
                                    "login_hero_feature_1": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "First bullet in the login hero."
                                    },
                                    "login_hero_feature_2": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Second bullet in the login hero."
                                    },
                                    "login_hero_feature_3": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Third bullet in the login hero."
                                    },
                                    "login_hero_subtitle": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Login hero sub-headline."
                                    },
                                    "login_hero_title": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Login hero headline."
                                    },
                                    "login_panel_subtitle": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Subtitle above the login form."
                                    },
                                    "login_panel_title": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Title above the login form."
                                    },
                                    "logo": {
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Logo image upload.",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "page_title_suffix": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Text appended to every browser tab title."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_config_mail/{id}": {
            "put": {
                "operationId": "put_api_update_config_mail_id",
                "tags": [
                    "Mail Settings"
                ],
                "summary": "Update mail server config",
                "description": "Overwrites the SMTP configuration. All listed fields are written as sent (an omitted field becomes null), so send the full set. Use `POST /api/test_config_mail` afterwards to verify.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "MailSettingsController@update_config_mail",
                "x-source": "app/Http/Controllers/MailSettingsController.php#L29-L46",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "mail_settings",
                        "slug": "mail_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Server"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Server row ID (always `1`)."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "encryption": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`tls`, `ssl` or empty."
                                    },
                                    "host": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "SMTP host."
                                    },
                                    "mail_mailer": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Transport: `smtp`, `sendmail`, `mailgun`, `ses`, `log`."
                                    },
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "SMTP password."
                                    },
                                    "port": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "SMTP port.",
                                        "type": "integer"
                                    },
                                    "sender_email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "From address."
                                    },
                                    "sender_name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "From name."
                                    },
                                    "username": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "SMTP username."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_custom_config": {
            "post": {
                "operationId": "post_api_update_custom_config",
                "tags": [
                    "SMS Settings"
                ],
                "summary": "Update custom HTTP SMS gateway",
                "description": "Configures a generic HTTP gateway. `headers` and `payload` are objects whose values may contain the placeholders `{phone}`, `{message}` and `{sender}`; they are JSON-encoded into `.env`. `success_keyword` is matched against the gateway response body to decide whether the send succeeded.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Sms_SettingsController@update_custom_config",
                "x-source": "app/Http/Controllers/Sms_SettingsController.php#L125-L156",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "sms_settings",
                        "slug": "sms_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "api_url": {
                                        "type": "string",
                                        "format": "uri",
                                        "x-laravel-rules": [
                                            "required",
                                            "url"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Endpoint URL."
                                    },
                                    "content_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "json",
                                            "form"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:json,form"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "How `payload` is sent: `json` body or `form` fields."
                                    },
                                    "headers": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Extra request headers.",
                                        "type": "object"
                                    },
                                    "method": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "GET",
                                            "POST",
                                            "PUT"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:GET,POST,PUT"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "HTTP method."
                                    },
                                    "payload": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Request body template.",
                                        "type": "object"
                                    },
                                    "sender": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Default sender ID."
                                    },
                                    "success_keyword": {
                                        "type": "string",
                                        "maxLength": 128,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:128"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Substring that indicates success in the response."
                                    }
                                },
                                "required": [
                                    "api_url",
                                    "content_type",
                                    "method"
                                ]
                            },
                            "example": {
                                "api_url": "https://sms.example.com/send",
                                "method": "POST",
                                "content_type": "json",
                                "headers": {
                                    "Authorization": "Bearer XXX"
                                },
                                "payload": {
                                    "to": "{phone}",
                                    "text": "{message}",
                                    "from": "{sender}"
                                },
                                "sender": "STOCKY",
                                "success_keyword": "\"status\":\"ok\""
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_custom_email": {
            "put": {
                "operationId": "put_api_update_custom_email",
                "tags": [
                    "Notification Templates"
                ],
                "summary": "Update an email template",
                "description": "Creates or updates the subject/body of one email type for a locale. The body is sanitised with HTMLPurifier: only basic block/inline tags and `font-size`, `color`, `background-color`, `text-align` styles survive. Send the payload as JSON.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Notifications_Template@update_custom_email",
                "x-source": "app/Http/Controllers/Notifications_Template.php#L226-L254",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "notification_template",
                        "slug": "notification_template",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "EmailMessage"
                ],
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_infobip_config": {
            "post": {
                "operationId": "post_api_update_infobip_config",
                "tags": [
                    "SMS Settings"
                ],
                "summary": "Update Infobip credentials",
                "description": "Writes the Infobip base URL, API key and sender to `.env` and rebuilds the config cache. Fields sent as `null` keep their current value.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Sms_SettingsController@update_infobip_config",
                "x-source": "app/Http/Controllers/Sms_SettingsController.php#L106-L121",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "sms_settings",
                        "slug": "sms_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "api_key": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "API key."
                                    },
                                    "base_url": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Infobip API base URL."
                                    },
                                    "sender_from": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sender name/number.",
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_mobile_settings": {
            "post": {
                "operationId": "post_api_update_mobile_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Update mobile-app settings",
                "description": "Partial multipart update of the mobile-app configuration. Upload `logo` to replace the app logo or send `remove_logo=1` to clear it. `mobile_modules` is a JSON-encoded array of module keys the app should expose.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@update_mobile_settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L2227-L2322",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "appearance_settings",
                        "slug": "appearance_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "logo": {
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "file",
                                            "image",
                                            "mimes:png,jpg,jpeg,webp",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Logo image (PNG/JPG/WebP, max 2 MB).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "mobile_allow_price_edit": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow editing unit prices in the app.",
                                        "type": "boolean"
                                    },
                                    "mobile_app_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow the mobile app to log in."
                                    },
                                    "mobile_app_name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name shown inside the mobile app."
                                    },
                                    "mobile_maintenance_message": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "When set, the app shows this message and blocks usage."
                                    },
                                    "mobile_min_version": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Minimum app version allowed to connect (older builds are told to update)."
                                    },
                                    "mobile_modules": {
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "JSON array of module keys enabled in the app.",
                                        "type": "string",
                                        "x-format": "JSON-encoded string"
                                    },
                                    "mobile_offline_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Allow offline mode in the app."
                                    },
                                    "mobile_primary_color": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-rules": [
                                            "regex:/^#[0-9a-fA-F]{6}$/"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "regex:/^#[0-9a-fA-F]{6}$/"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Hex accent colour (`#RRGGBB`)."
                                    },
                                    "mobile_scanner_enabled": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Enable the camera barcode scanner."
                                    },
                                    "mobile_support_email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "email",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Support email shown in the app."
                                    },
                                    "mobile_support_phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Support phone shown in the app."
                                    },
                                    "mobile_theme_mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "system",
                                            "light",
                                            "dark"
                                        ],
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "in:system,light,dark"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Theme forced on the app."
                                    },
                                    "remove_logo": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Set to `1` to delete the current logo.",
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_pwa_settings": {
            "post": {
                "operationId": "post_api_update_pwa_settings",
                "tags": [
                    "System Settings"
                ],
                "summary": "Update PWA settings",
                "description": "Saves the PWA identity and optionally replaces the icons. Uploaded icons are resized to 192×192 / 512×512 and written to `public/pwa_images/pwa-icon-{192,512}.png`. Empty identity fields clear the override so the manifest falls back to the app name and built-in defaults. `pwa_start_url` must be a path starting with `/` (same-origin only).",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "SettingsController@update_pwa_settings",
                "x-source": "app/Http/Controllers/SettingsController.php#L2055-L2104",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "appearance_settings",
                        "slug": "appearance_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "icon_192": {
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "file",
                                            "image",
                                            "mimes:png,jpg,jpeg,webp",
                                            "max:1024"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "192×192 icon upload (PNG/JPG/WebP, max 1 MB).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "icon_512": {
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "file",
                                            "image",
                                            "mimes:png,jpg,jpeg,webp",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "512×512 icon upload (PNG/JPG/WebP, max 2 MB).",
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "pwa_background_color": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-rules": [
                                            "regex:/^#[0-9a-fA-F]{6}$/"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "regex:/^#[0-9a-fA-F]{6}$/"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Hex splash background colour (`#RRGGBB`)."
                                    },
                                    "pwa_description": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:255"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Manifest description."
                                    },
                                    "pwa_display": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "standalone",
                                            "fullscreen",
                                            "minimal-ui",
                                            "browser"
                                        ],
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "in:standalone,fullscreen,minimal-ui,browser"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Manifest display mode."
                                    },
                                    "pwa_enabled": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Serve the manifest and service worker.",
                                        "type": "boolean"
                                    },
                                    "pwa_name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Full app name in the manifest."
                                    },
                                    "pwa_orientation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "any",
                                            "portrait",
                                            "landscape"
                                        ],
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "in:any,portrait,landscape"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Preferred screen orientation."
                                    },
                                    "pwa_short_name": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Short name shown under the home-screen icon."
                                    },
                                    "pwa_start_url": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-rules": [
                                            "regex:/^\\//"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "max:191",
                                            "regex:/^\\//"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Path opened when the installed app launches (e.g. `/pos`)."
                                    },
                                    "pwa_theme_color": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-rules": [
                                            "regex:/^#[0-9a-fA-F]{6}$/"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "nullable",
                                            "string",
                                            "regex:/^#[0-9a-fA-F]{6}$/"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Hex theme colour (`#RRGGBB`)."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{success: true, saved: {...}}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "saved": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_sms_body": {
            "put": {
                "operationId": "put_api_update_sms_body",
                "tags": [
                    "Notification Templates"
                ],
                "summary": "Update an SMS template",
                "description": "Creates or updates the SMS text for one notification type and locale. Placeholders such as `{contact_name}`, `{number}`, `{total_amount}`, `{due_amount}` and `{business_name}` are replaced at send time.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Notifications_Template@update_sms_body",
                "x-source": "app/Http/Controllers/Notifications_Template.php#L104-L119",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "notification_template",
                        "slug": "notification_template",
                        "policy": "SettingPolicy"
                    }
                ],
                "x-models": [
                    "SMSMessage"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "locale": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Locale code (default `en`)."
                                    },
                                    "sms_body": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Message text with placeholders."
                                    },
                                    "sms_body_type": {
                                        "type": "string",
                                        "enum": [
                                            "sale",
                                            "quotation",
                                            "payment_received",
                                            "purchase",
                                            "payment_sent",
                                            "subscription_reminder",
                                            "asset_validation_due"
                                        ],
                                        "description": "Notification type.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "sms_body_type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_social_profile/{id}": {
            "put": {
                "operationId": "put_api_update_social_profile_id",
                "tags": [
                    "Employees"
                ],
                "summary": "Update an employee's social profiles",
                "description": "Stores the employee's social links (Facebook, LinkedIn, Twitter, Skype, WhatsApp) shown on the profile card.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeesController@update_social_profile",
                "x-source": "app/Http/Controllers/hrm/EmployeesController.php#L301-L315",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "Employee"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Employee id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "facebook": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Facebook URL."
                                    },
                                    "linkedin": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "LinkedIn URL."
                                    },
                                    "skype": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Skype."
                                    },
                                    "twitter": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Twitter URL."
                                    },
                                    "whatsapp": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "WhatsApp number."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_status_module": {
            "post": {
                "operationId": "post_api_update_status_module",
                "tags": [
                    "Module Settings"
                ],
                "summary": "Enable or disable a module",
                "description": "Enables or disables an installed module by name. Disabled modules keep their files and data but their routes and menus disappear.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "ModuleSettingsController@update_status_module",
                "x-source": "app/Http/Controllers/ModuleSettingsController.php#L28-L48",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Module name (directory name)."
                                    },
                                    "status": {
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Truthy to enable, falsy to disable.",
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "name",
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{message}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Module status updated"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "description": "Module not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Module not found"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_task_status/{id}": {
            "put": {
                "operationId": "put_api_update_task_status_id",
                "tags": [
                    "Tasks"
                ],
                "summary": "Move a task to a status (by path id)",
                "description": "Same as the POST variant, addressed by route parameter.",
                "x-section": "Work Management",
                "x-surface": "admin",
                "x-controller": "TaskController@update_task_status",
                "x-source": "app/Http/Controllers/TaskController.php#L358-L372",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "tasks",
                        "policy": "TaskPolicy"
                    }
                ],
                "x-models": [
                    "Task"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Task id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "status": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "not_started",
                                            "progress",
                                            "completed",
                                            "cancelled"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:not_started,progress,completed,cancelled"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Target status."
                                    }
                                },
                                "required": [
                                    "status"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_termi_config": {
            "post": {
                "operationId": "post_api_update_termi_config",
                "tags": [
                    "SMS Settings"
                ],
                "summary": "Update Termii credentials",
                "description": "Writes the Termii key, secret and sender ID to `.env` and rebuilds the config cache. Fields sent as `null` keep their current value.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Sms_SettingsController@update_termi_config",
                "x-source": "app/Http/Controllers/Sms_SettingsController.php#L86-L102",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "sms_settings",
                        "slug": "sms_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "TERMI_KEY": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "API key."
                                    },
                                    "TERMI_SECRET": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "API secret."
                                    },
                                    "TERMI_SENDER": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sender ID."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_twilio_config": {
            "post": {
                "operationId": "post_api_update_twilio_config",
                "tags": [
                    "SMS Settings"
                ],
                "summary": "Update Twilio credentials",
                "description": "Writes the Twilio SID, auth token and sender number to `.env`. Fields sent as `null` keep their current value.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "Sms_SettingsController@update_twilio_config",
                "x-source": "app/Http/Controllers/Sms_SettingsController.php#L67-L82",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "sms_settings",
                        "slug": "sms_settings | setting_system",
                        "policy": "SettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "TWILIO_FROM": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sender phone number in E.164 format.",
                                        "type": "string"
                                    },
                                    "TWILIO_SID": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Account SID."
                                    },
                                    "TWILIO_TOKEN": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Auth token."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{success: true}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_user_password": {
            "post": {
                "operationId": "post_api_update_user_password",
                "tags": [
                    "Users"
                ],
                "summary": "Update my password",
                "description": "Changes the authenticated user's password after checking `current_password`. `new_password` must be 6–14 characters and repeated in `new_password_confirmation`.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@updatePassword",
                "x-source": "app/Http/Controllers/UserController.php#L413-L436",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "current_password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "The user's current password."
                                    },
                                    "new_password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "minLength": 6,
                                        "maxLength": 14,
                                        "x-rules": [
                                            "confirmed (send <field>_confirmation)"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "min:6",
                                            "max:14",
                                            "confirmed"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "New password, 6–14 chars, confirmed by `new_password_confirmation`."
                                    }
                                },
                                "required": [
                                    "current_password",
                                    "new_password"
                                ]
                            },
                            "example": {
                                "current_password": "123456",
                                "new_password": "NewPass#26",
                                "new_password_confirmation": "NewPass#26"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success: true` with a translated confirmation message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/update_user_profile/{id}": {
            "put": {
                "operationId": "put_api_update_user_profile_id",
                "tags": [
                    "Users"
                ],
                "summary": "Update my profile",
                "description": "Lets the logged-in user change their own name, username, email, phone and avatar. The `id` in the URL is ignored — the **authenticated user** is always the one updated. Passwords are changed with *Update my password*.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@updateProfile",
                "x-source": "app/Http/Controllers/UserController.php#L358-L409",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "User"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Ignored; the caller's own id is used."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "avatar": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Optional new image file (multipart)."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "users",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::unique('users')->ignore($id)"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:users",
                                            "dynamic:\\Illuminate\\Validation\\Rule::unique('users')->ignore($id)"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Email; unique among users. Required."
                                    },
                                    "firstname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "First name. Required."
                                    },
                                    "lastname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Last name. Required."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Phone. Required."
                                    },
                                    "username": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Display name. Required."
                                    }
                                },
                                "required": [
                                    "email",
                                    "firstname",
                                    "lastname",
                                    "phone",
                                    "username"
                                ]
                            },
                            "example": {
                                "firstname": "William",
                                "lastname": "Castillo",
                                "username": "William Castillo",
                                "email": "admin@example.com",
                                "phone": "0123456789"
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "New `avatar` file name and the `username` that was saved.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "avatar": {
                                            "type": "string"
                                        },
                                        "user": {}
                                    }
                                },
                                "example": {
                                    "avatar": "38492817photo.png",
                                    "user": "William Castillo"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/upload_module": {
            "post": {
                "operationId": "post_api_upload_module",
                "tags": [
                    "Module Settings"
                ],
                "summary": "Upload a module ZIP",
                "description": "Extracts the ZIP into `Modules/<name>` (the archive must contain a single top-level folder with a `module.json`), then registers it.",
                "x-section": "System & Settings",
                "x-surface": "admin",
                "x-controller": "ModuleSettingsController@upload_module",
                "x-source": "app/Http/Controllers/ModuleSettingsController.php#L50-L114",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "module_zip": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:zip",
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "mimes:zip"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Module package ZIP."
                                    }
                                },
                                "required": [
                                    "module_zip"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{message}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Module uploaded successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/user": {
            "get": {
                "operationId": "get_api_user",
                "tags": [
                    "Authentication"
                ],
                "summary": "Get the authenticated user",
                "description": "Returns the user record that owns the token used for the request. Handy for verifying a token and reading the user's id, username, email, role and avatar.",
                "x-section": "Authentication & Public",
                "x-surface": "admin",
                "x-middleware": [
                    "api",
                    "auth:api"
                ],
                "responses": {
                    "200": {
                        "description": "The `users` row of the caller (password hash excluded)."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/users": {
            "get": {
                "operationId": "get_api_users",
                "tags": [
                    "Users"
                ],
                "summary": "List users",
                "description": "Paginated list of users. A caller **without** record-view sees only their own account. `search` matches username, first/last name, email and phone. Also returns the `roles` and `warehouses` lookups used by the create/edit form.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@index",
                "x-source": "app/Http/Controllers/UserController.php#L25-L84",
                "x-route-name": "users.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "users_view",
                        "policy": "UserPolicy"
                    }
                ],
                "x-paginated": true,
                "x-filter-columns": [
                    "username",
                    "statut",
                    "phone",
                    "email"
                ],
                "x-models": [
                    "User",
                    "Role",
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "email",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on email."
                    },
                    {
                        "name": "phone",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on phone."
                    },
                    {
                        "name": "statut",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "boolean",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on active flag: `1` active, `0` disabled (exact match)."
                    },
                    {
                        "name": "username",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "filter"
                            ]
                        },
                        "description": "Filter on username (`LIKE`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`users[]`, `roles[]`, `warehouses[]`, `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "users": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "roles": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "users": [
                                        {
                                            "id": 1,
                                            "firstname": "William",
                                            "lastname": "Castillo",
                                            "username": "William Castillo",
                                            "email": "admin@example.com",
                                            "phone": "0123456789",
                                            "avatar": "no_avatar.png",
                                            "role_id": 1,
                                            "statut": 1,
                                            "is_all_warehouses": 1,
                                            "record_view": 1
                                        }
                                    ],
                                    "roles": [
                                        {
                                            "id": 1,
                                            "name": "Owner"
                                        }
                                    ],
                                    "warehouses": [
                                        {
                                            "id": 1,
                                            "name": "Main"
                                        }
                                    ],
                                    "totalRows": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_users",
                "tags": [
                    "Users"
                ],
                "summary": "Create a user",
                "description": "Creates a staff user. Send as `multipart/form-data` when uploading an avatar (resized to 128×128 and stored under `/images/avatar/`); otherwise JSON works. The user gets the role in `role` (also written to the `role_user` pivot). When `is_all_warehouses` is false, `assigned_to` lists the warehouse ids the user may work in.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@store",
                "x-source": "app/Http/Controllers/UserController.php#L176-L237",
                "x-route-name": "users.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "users_add",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "User",
                    "role_user"
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "assigned_to": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of warehouse ids the user is restricted to (ignored when `is_all_warehouses` is true)."
                                    },
                                    "avatar": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Optional image file."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-unique": "users",
                                        "x-laravel-rules": [
                                            "required",
                                            "unique:users"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Login email; must be unique among users. Required."
                                    },
                                    "firstname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "is_all_warehouses": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1`/`true` = access to every warehouse; otherwise only `assigned_to`."
                                    },
                                    "lastname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Initial password (stored hashed)."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number (stored as empty string when omitted)."
                                    },
                                    "record_view": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1`/`true` = the user sees all records; `0` = only records they created. Default `0`."
                                    },
                                    "role": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Role id."
                                    },
                                    "username": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Display / login name."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "firstname": "Sara",
                                "lastname": "K",
                                "username": "sara",
                                "email": "sara@example.com",
                                "password": "Secret123",
                                "phone": "0600000000",
                                "role": 2,
                                "is_all_warehouses": false,
                                "assigned_to": [
                                    1,
                                    3
                                ],
                                "record_view": false
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/users/{user}": {
            "delete": {
                "operationId": "delete_api_users_user",
                "tags": [
                    "Users"
                ],
                "summary": "Delete a user",
                "description": "Soft-deletes the user and sets `statut = 0`. You cannot delete your own account (`403`).",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@destroy",
                "x-source": "app/Http/Controllers/UserController.php#L462-L486",
                "x-route-name": "users.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "users_delete",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "User"
                ],
                "parameters": [
                    {
                        "name": "user",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "User id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Attempt to delete the calling user's own account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "You cannot delete your own account."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_users_user",
                "tags": [
                    "Users"
                ],
                "summary": "(Not implemented) Get a user",
                "description": "Resource stub with an empty body; returns an empty `200`. Use `GET /api/users/{user}/edit` to load a user.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@show",
                "x-source": "app/Http/Controllers/UserController.php#L241-L245",
                "x-route-name": "users.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "user",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "User id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_users_user",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Users"
                ],
                "summary": "Update a user",
                "description": "Updates a staff user. `email` must remain unique (the user's own row is ignored). The password is changed only when `NewPassword` is non-empty and not the literal string `\"null\"`; otherwise it is kept. A new `avatar` replaces and deletes the previous file. The role pivot and assigned warehouses are re-synced.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@update",
                "x-source": "app/Http/Controllers/UserController.php#L267-L354",
                "x-route-name": "users.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "users_edit",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "User",
                    "role_user"
                ],
                "parameters": [
                    {
                        "name": "user",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "User id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "NewPassword": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "New password, or empty to keep the current one."
                                    },
                                    "assigned_to": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse ids when not all warehouses."
                                    },
                                    "avatar": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Optional new image file."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "users",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::unique('users')->ignore($id)"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:users",
                                            "dynamic:\\Illuminate\\Validation\\Rule::unique('users')->ignore($id)"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Login email; unique. Required."
                                    },
                                    "firstname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "is_all_warehouses": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Access to all warehouses flag."
                                    },
                                    "lastname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number."
                                    },
                                    "record_view": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "See-all-records flag."
                                    },
                                    "role": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Role id."
                                    },
                                    "statut": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1` active / `0` disabled."
                                    },
                                    "username": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Display name."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "firstname": "Sara",
                                "lastname": "K",
                                "username": "sara",
                                "email": "sara@example.com",
                                "phone": "0600000000",
                                "role": 2,
                                "statut": 1,
                                "is_all_warehouses": true,
                                "record_view": true,
                                "NewPassword": ""
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_users_user",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Users"
                ],
                "summary": "Update a user",
                "description": "Updates a staff user. `email` must remain unique (the user's own row is ignored). The password is changed only when `NewPassword` is non-empty and not the literal string `\"null\"`; otherwise it is kept. A new `avatar` replaces and deletes the previous file. The role pivot and assigned warehouses are re-synced.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@update",
                "x-source": "app/Http/Controllers/UserController.php#L267-L354",
                "x-route-name": "users.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "users_edit",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "User",
                    "role_user"
                ],
                "parameters": [
                    {
                        "name": "user",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "User id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "NewPassword": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "New password, or empty to keep the current one."
                                    },
                                    "assigned_to": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Warehouse ids when not all warehouses."
                                    },
                                    "avatar": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-sources": [
                                            "file"
                                        ],
                                        "description": "Optional new image file."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-unique": "users",
                                        "x-rules": [
                                            "dynamic:\\Illuminate\\Validation\\Rule::unique('users')->ignore($id)"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "unique:users",
                                            "dynamic:\\Illuminate\\Validation\\Rule::unique('users')->ignore($id)"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Login email; unique. Required."
                                    },
                                    "firstname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "First name."
                                    },
                                    "is_all_warehouses": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Access to all warehouses flag."
                                    },
                                    "lastname": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Last name."
                                    },
                                    "phone": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number."
                                    },
                                    "record_view": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "See-all-records flag."
                                    },
                                    "role": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Role id."
                                    },
                                    "statut": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1` active / `0` disabled."
                                    },
                                    "username": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Display name."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            },
                            "example": {
                                "firstname": "Sara",
                                "lastname": "K",
                                "username": "sara",
                                "email": "sara@example.com",
                                "phone": "0600000000",
                                "role": 2,
                                "statut": 1,
                                "is_all_warehouses": true,
                                "record_view": true,
                                "NewPassword": ""
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/users/{user}/edit": {
            "get": {
                "operationId": "get_api_users_user_edit",
                "tags": [
                    "Users"
                ],
                "summary": "Get a user for editing",
                "description": "Returns the user record plus everything the edit form needs: `assigned_warehouses` (ids currently assigned), `roles` and the full `warehouses` list.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@edit",
                "x-source": "app/Http/Controllers/UserController.php#L247-L263",
                "x-route-name": "users.edit",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "users_edit",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "User",
                    "UserWarehouse",
                    "Warehouse",
                    "Role"
                ],
                "parameters": [
                    {
                        "name": "user",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "User id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`user`, `assigned_warehouses[]`, `roles[]`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "user": {},
                                        "assigned_warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "roles": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "user": {
                                        "id": 4,
                                        "firstname": "Sara",
                                        "lastname": "K",
                                        "username": "sara",
                                        "email": "sara@example.com",
                                        "phone": "0600000000",
                                        "role_id": 2,
                                        "statut": 1,
                                        "is_all_warehouses": 0,
                                        "record_view": 0,
                                        "avatar": "no_avatar.png"
                                    },
                                    "assigned_warehouses": [
                                        1,
                                        3
                                    ],
                                    "roles": [
                                        {
                                            "id": 1,
                                            "name": "Owner"
                                        },
                                        {
                                            "id": 2,
                                            "name": "Cashier"
                                        }
                                    ],
                                    "warehouses": [
                                        {
                                            "id": 1,
                                            "name": "Main"
                                        },
                                        {
                                            "id": 3,
                                            "name": "Depot"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/users_list_for_select": {
            "get": {
                "operationId": "get_api_users_list_for_select",
                "tags": [
                    "Users"
                ],
                "summary": "List active users for pickers",
                "description": "All active, non-deleted users ordered by name, with only `id, firstname, lastname, username, email`. Requires authentication only (no `users_view`), intended for dropdowns such as linking a sales agent or assigning a task.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@listForSelect",
                "x-source": "app/Http/Controllers/UserController.php#L493-L502",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "User"
                ],
                "responses": {
                    "200": {
                        "description": "`users[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "users": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "users": [
                                        {
                                            "id": 1,
                                            "firstname": "William",
                                            "lastname": "Castillo",
                                            "username": "William Castillo",
                                            "email": "admin@example.com"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/users_switch_activated/{id}": {
            "put": {
                "operationId": "put_api_users_switch_activated_id",
                "tags": [
                    "Users"
                ],
                "summary": "Activate or deactivate a user",
                "description": "Sets the `statut` flag of another user. Deactivated users cannot log in and are logged out on their next request. Returns `success: false` (HTTP 200) when the body `id` equals the caller's own id.",
                "x-section": "People",
                "x-surface": "admin",
                "x-controller": "UserController@IsActivated",
                "x-source": "app/Http/Controllers/UserController.php#L440-L459",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "users_edit",
                        "policy": "UserPolicy"
                    }
                ],
                "x-models": [
                    "User"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "User id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "statut": {
                                        "x-inferred": true,
                                        "type": "boolean",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`1` to activate, `0` to deactivate."
                                    }
                                }
                            },
                            "example": {
                                "statut": 0
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }` or `{ \"success\": false }` when targeting yourself.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/vehicles/catalog": {
            "get": {
                "operationId": "get_api_vehicles_catalog",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Get makes with their models",
                "description": "Full vehicle catalogue for the admin page: every make (`id, name, active`) with its `models[]` (`id, name, active`), plus `enabled` — whether the fitment feature is switched on.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@catalog",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L25-L47",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "products_view",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "VehicleMake"
                ],
                "responses": {
                    "200": {
                        "description": "`makes[]` and `enabled`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "makes": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "enabled": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/vehicles/incompatible_ids": {
            "post": {
                "operationId": "post_api_vehicles_incompatible_ids",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Get products that do not fit a vehicle",
                "description": "Given a vehicle (`make_id`, `model_id`, optional `year`, `engine`), returns the ids of products that **have** fitment data but do **not** fit it, so POS can hide them. Universal products (no fitment rows) are never listed. Any authenticated user may call it.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@incompatibleIds",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L246-L266",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "ProductFitment"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": true,
                                "x-accepts-all-input": true,
                                "properties": {
                                    "make_id": {
                                        "type": "integer",
                                        "description": "Vehicle make id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "model_id": {
                                        "type": "integer",
                                        "description": "Vehicle model id.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "year": {
                                        "type": "integer",
                                        "description": "Model year.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "engine": {
                                        "type": "string",
                                        "description": "Engine code.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "make_id"
                                ]
                            },
                            "example": {
                                "make_id": 1,
                                "model_id": 10,
                                "year": 2016
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Normalised `vehicle` and `incompatible_ids[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "vehicle": {},
                                        "incompatible_ids": {}
                                    }
                                },
                                "example": {
                                    "vehicle": {
                                        "make_id": 1,
                                        "model_id": 10,
                                        "year": 2016,
                                        "engine": null
                                    },
                                    "incompatible_ids": [
                                        23,
                                        57,
                                        90
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "description": "`error` when the vehicle data is invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/vehicles/lookup": {
            "get": {
                "operationId": "get_api_vehicles_lookup",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Get active makes and models (pickers)",
                "description": "Active makes and models for cascading selects (`models[].vehicle_make_id` links to the make). Requires authentication only, so cashiers can use it in POS.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@lookup",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L52-L62",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "VehicleMake",
                    "VehicleModel"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `makes[]`, `models[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {},
                                        "makes": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "models": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "enabled": true,
                                    "makes": [
                                        {
                                            "id": 1,
                                            "name": "Toyota"
                                        }
                                    ],
                                    "models": [
                                        {
                                            "id": 10,
                                            "vehicle_make_id": 1,
                                            "name": "Corolla"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/vehicles/makes": {
            "post": {
                "operationId": "post_api_vehicles_makes",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Create a make",
                "description": "Creates a vehicle make. Returns HTTP **201** with the row.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@storeMake",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L64-L70",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "VehicleMake"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-unique": "vehicle_makes,name",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100",
                                            "unique:vehicle_makes,name"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Make name, max 100, unique."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The created make.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/vehicles/makes/{id}": {
            "delete": {
                "operationId": "delete_api_vehicles_makes_id",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Delete a make",
                "description": "Deletes the make together with its models, every product fitment referencing them and customers' garage vehicles of that make.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@destroyMake",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L89-L103",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "VehicleMake",
                    "VehicleModel",
                    "ProductFitment",
                    "CustomerVehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Make id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_vehicles_makes_id",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Update a make",
                "description": "Renames a make and/or toggles `active` (inactive makes disappear from pickers but keep their fitments).",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@updateMake",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L72-L87",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "VehicleMake"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Make id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag; omit to keep."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-rules": [
                                            "dynamic:'required|string|max:100|unique:vehicle_makes,name,' . $make->id"
                                        ],
                                        "x-laravel-rules": [
                                            "dynamic:'required|string|max:100|unique:vehicle_makes,name,' . $make->id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name, unique."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "The updated make.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/vehicles/models": {
            "post": {
                "operationId": "post_api_vehicles_models",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Create a model",
                "description": "Creates a model under a make. Names are unique per make (case-insensitive). Returns HTTP **201**.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@storeModel",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L105-L124",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "VehicleModel"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Model name, max 100."
                                    },
                                    "vehicle_make_id": {
                                        "type": "integer",
                                        "x-exists": "vehicle_makes,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:vehicle_makes,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Parent make id."
                                    }
                                },
                                "required": [
                                    "name",
                                    "vehicle_make_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The created model.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/vehicles/models/{id}": {
            "delete": {
                "operationId": "delete_api_vehicles_models_id",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Delete a model",
                "description": "Deletes the model, the fitments referencing it and matching garage vehicles.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@destroyModel",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L143-L155",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "VehicleModel",
                    "ProductFitment",
                    "CustomerVehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Model id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_vehicles_models_id",
                "tags": [
                    "Vehicle Fitment"
                ],
                "summary": "Update a model",
                "description": "Renames a model and/or toggles `active`.",
                "x-section": "Catalog",
                "x-surface": "admin",
                "x-controller": "VehicleFitmentController@updateModel",
                "x-source": "app/Http/Controllers/VehicleFitmentController.php#L126-L141",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "products_edit",
                        "policy": "ProductPolicy"
                    }
                ],
                "x-models": [
                    "VehicleModel"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Model id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Model name."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The updated model.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/warehouse_locations": {
            "get": {
                "operationId": "get_api_warehouse_locations",
                "tags": [
                    "Warehouse Locations"
                ],
                "summary": "List warehouse locations",
                "description": "Paginated locations limited to the caller's warehouses. Rows: `id, warehouse_id, warehouse (name), code, name, is_active`. `search` matches code or name. Also returns the caller's `warehouses` for the filter dropdown.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseLocationController@index",
                "x-source": "app/Http/Controllers/WarehouseLocationController.php#L14-L83",
                "x-route-name": "warehouse_locations.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "warehouse_locations",
                        "policy": "WarehouseLocationPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse",
                    "UserWarehouse",
                    "WarehouseLocation"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "warehouse_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Only locations of this warehouse (ignored if not assigned to the caller)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`locations[]`, `totalRows`, `warehouses[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "warehouse_id": {},
                                        "warehouse": {},
                                        "code": {},
                                        "name": {},
                                        "is_active": {
                                            "type": "boolean"
                                        },
                                        "locations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                },
                                "example": {
                                    "locations": [
                                        {
                                            "id": 9,
                                            "warehouse_id": 1,
                                            "warehouse": "Main",
                                            "code": "A-03-2",
                                            "name": "Aisle A, rack 3, shelf 2",
                                            "is_active": true
                                        }
                                    ],
                                    "totalRows": 1,
                                    "warehouses": [
                                        {
                                            "id": 1,
                                            "name": "Main"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_warehouse_locations",
                "tags": [
                    "Warehouse Locations"
                ],
                "summary": "Create a warehouse location",
                "description": "Creates a location in one of the caller's warehouses. `code` must be unique within that warehouse. `is_active` defaults to `true`.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseLocationController@store",
                "x-source": "app/Http/Controllers/WarehouseLocationController.php#L85-L117",
                "x-route-name": "warehouse_locations.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "warehouse_locations",
                        "policy": "WarehouseLocationPolicy"
                    }
                ],
                "x-models": [
                    "WarehouseLocation"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-unique": "warehouse_locations ->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64",
                                            "unique:warehouse_locations ->where"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Location code, max 64."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Descriptive name, max 192."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-enum-source": "$allowedWarehouseIds",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "in:$allowedWarehouseIds"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id (must be assigned to the caller)."
                                    }
                                },
                                "required": [
                                    "code",
                                    "warehouse_id"
                                ]
                            },
                            "example": {
                                "warehouse_id": 1,
                                "code": "B-01-1",
                                "name": "Aisle B, rack 1, shelf 1",
                                "is_active": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the created `location`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "location": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/warehouse_locations/by_warehouse/{id}": {
            "get": {
                "operationId": "get_api_warehouse_locations_by_warehouse_id",
                "tags": [
                    "Warehouse Locations"
                ],
                "summary": "List active locations of a warehouse",
                "description": "Active locations of one warehouse as `{id, warehouse_id, code, name}` ordered by code — for the location picker on product and document forms. Returns an empty array when the warehouse is not assigned to the caller.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseLocationController@by_warehouse",
                "x-source": "app/Http/Controllers/WarehouseLocationController.php#L165-L181",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "warehouse_locations",
                        "policy": "WarehouseLocationPolicy"
                    }
                ],
                "x-models": [
                    "WarehouseLocation"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of locations.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/warehouse_locations/{warehouse_location}": {
            "delete": {
                "operationId": "delete_api_warehouse_locations_warehouse_location",
                "tags": [
                    "Warehouse Locations"
                ],
                "summary": "Delete a warehouse location",
                "description": "Soft-deletes the location; products assigned to it lose the reference in pickers.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseLocationController@destroy",
                "x-source": "app/Http/Controllers/WarehouseLocationController.php#L154-L163",
                "x-route-name": "warehouse_locations.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "warehouse_locations",
                        "policy": "WarehouseLocationPolicy"
                    }
                ],
                "x-models": [
                    "WarehouseLocation"
                ],
                "parameters": [
                    {
                        "name": "warehouse_location",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Location id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_warehouse_locations_warehouse_location",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Warehouse Locations"
                ],
                "summary": "Update a warehouse location",
                "description": "Updates warehouse, code, name and active flag (omitting `is_active` keeps the current value).",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseLocationController@update",
                "x-source": "app/Http/Controllers/WarehouseLocationController.php#L119-L152",
                "x-route-name": "warehouse_locations.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "warehouse_locations",
                        "policy": "WarehouseLocationPolicy"
                    }
                ],
                "x-models": [
                    "WarehouseLocation"
                ],
                "parameters": [
                    {
                        "name": "warehouse_location",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Location id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-unique": "warehouse_locations ->ignore->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64",
                                            "unique:warehouse_locations ->ignore->where"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Location code, unique per warehouse."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-enum-source": "$allowedWarehouseIds",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "in:$allowedWarehouseIds"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                },
                                "required": [
                                    "code",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the updated `location`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "location": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_warehouse_locations_warehouse_location",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Warehouse Locations"
                ],
                "summary": "Update a warehouse location",
                "description": "Updates warehouse, code, name and active flag (omitting `is_active` keeps the current value).",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseLocationController@update",
                "x-source": "app/Http/Controllers/WarehouseLocationController.php#L119-L152",
                "x-route-name": "warehouse_locations.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "warehouse_locations",
                        "policy": "WarehouseLocationPolicy"
                    }
                ],
                "x-models": [
                    "WarehouseLocation"
                ],
                "parameters": [
                    {
                        "name": "warehouse_location",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Location id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-unique": "warehouse_locations ->ignore->where",
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64",
                                            "unique:warehouse_locations ->ignore->where"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Location code, unique per warehouse."
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Active flag."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 192,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:192"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "x-enum-source": "$allowedWarehouseIds",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "in:$allowedWarehouseIds"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse id."
                                    }
                                },
                                "required": [
                                    "code",
                                    "warehouse_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and the updated `location`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "location": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/warehouses": {
            "get": {
                "operationId": "get_api_warehouses",
                "tags": [
                    "Warehouses"
                ],
                "summary": "List warehouses",
                "description": "Paginated warehouses (all of them, regardless of the caller's assignments). `search` matches name, mobile, country, city, zip and email.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseController@index",
                "x-source": "app/Http/Controllers/WarehouseController.php#L16-L54",
                "x-route-name": "warehouses.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "warehouse",
                        "policy": "WarehousePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Warehouse"
                ],
                "x-notes": [
                    "`SortField`/`SortType` are passed directly to `ORDER BY` – send both."
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`warehouses[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "warehouses": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                },
                                "example": {
                                    "warehouses": [
                                        {
                                            "id": 1,
                                            "name": "Main",
                                            "mobile": "0600000000",
                                            "country": "MA",
                                            "city": "Casablanca",
                                            "zip": "20000",
                                            "email": "main@example.com"
                                        }
                                    ],
                                    "totalRows": 1
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_warehouses",
                "tags": [
                    "Warehouses"
                ],
                "summary": "Create a warehouse",
                "description": "Creates a warehouse and immediately inserts a `product_warehouse` row (quantity 0, `manage_stock` 0 for services) for every existing product and variant so stock can be tracked there.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseController@store",
                "x-source": "app/Http/Controllers/WarehouseController.php#L58-L112",
                "x-route-name": "warehouses.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "warehouse",
                        "policy": "WarehousePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "Product",
                    "ProductVariant",
                    "product_warehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email address."
                                    },
                                    "mobile": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone number."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Warehouse name. Required."
                                    },
                                    "zip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            },
                            "example": {
                                "name": "Depot North",
                                "mobile": "0600000001",
                                "country": "MA",
                                "city": "Tangier",
                                "zip": "90000",
                                "email": "north@example.com"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/warehouses/delete/by_selection": {
            "post": {
                "operationId": "post_api_warehouses_delete_by_selection",
                "tags": [
                    "Warehouses"
                ],
                "summary": "Delete several warehouses",
                "description": "Soft-deletes each warehouse in `selectedIds` together with its stock rows.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseController@delete_by_selection",
                "x-source": "app/Http/Controllers/WarehouseController.php#L167-L187",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "warehouse",
                        "policy": "WarehousePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "product_warehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "selectedIds": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Array of warehouse ids.",
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/warehouses/{warehouse}": {
            "delete": {
                "operationId": "delete_api_warehouses_warehouse",
                "tags": [
                    "Warehouses"
                ],
                "summary": "Delete a warehouse",
                "description": "Soft-deletes the warehouse **and all its stock rows** (`product_warehouse`). Documents that reference the warehouse are kept.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseController@destroy",
                "x-source": "app/Http/Controllers/WarehouseController.php#L146-L163",
                "x-route-name": "warehouses.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "warehouse",
                        "policy": "WarehousePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse",
                    "product_warehouse"
                ],
                "parameters": [
                    {
                        "name": "warehouse",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Warehouse id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_warehouses_warehouse",
                "tags": [
                    "Warehouses"
                ],
                "summary": "(Not implemented) Get a warehouse",
                "description": "Resource stub with an empty body; returns an empty `200`. Use the list endpoint.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseController@show",
                "x-source": "app/Http/Controllers/WarehouseController.php#L116-L120",
                "x-route-name": "warehouses.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "warehouse",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Warehouse id (ignored)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Empty body."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_warehouses_warehouse",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Warehouses"
                ],
                "summary": "Update a warehouse",
                "description": "Replaces the warehouse's contact fields.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseController@update",
                "x-source": "app/Http/Controllers/WarehouseController.php#L124-L142",
                "x-route-name": "warehouses.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "warehouse",
                        "policy": "WarehousePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "name": "warehouse",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Warehouse id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "mobile": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    },
                                    "zip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_warehouses_warehouse",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Warehouses"
                ],
                "summary": "Update a warehouse",
                "description": "Replaces the warehouse's contact fields.",
                "x-section": "Inventory",
                "x-surface": "admin",
                "x-controller": "WarehouseController@update",
                "x-source": "app/Http/Controllers/WarehouseController.php#L124-L142",
                "x-route-name": "warehouses.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "warehouse",
                        "policy": "WarehousePolicy"
                    }
                ],
                "x-models": [
                    "Warehouse"
                ],
                "parameters": [
                    {
                        "name": "warehouse",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Warehouse id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "city": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "email": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Email."
                                    },
                                    "mobile": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Phone."
                                    },
                                    "name": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Name. Required."
                                    },
                                    "zip": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Postal code."
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/webhooks": {
            "get": {
                "operationId": "get_api_webhooks",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "List webhooks",
                "description": "Paginated; `search` matches name or URL.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@index",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L20-L49",
                "x-route-name": "webhooks.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Webhook"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`webhooks[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "webhooks": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_webhooks",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Create a webhook",
                "description": "A signing `secret` is generated.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@store",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L51-L73",
                "x-route-name": "webhooks.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "webhooks_add",
                        "policy": "WebhookPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "events": {
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Event names to subscribe to.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "headers": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Extra HTTP headers `{name: value}`.",
                                        "type": "object"
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "timeout_seconds": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Request timeout 1–60."
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 2048,
                                        "x-laravel-rules": [
                                            "required",
                                            "url",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Target URL."
                                    }
                                },
                                "required": [
                                    "events",
                                    "name",
                                    "url"
                                ]
                            },
                            "example": {
                                "name": "ERP bridge",
                                "url": "https://example.com/hooks/stocky",
                                "events": [
                                    "sale.created",
                                    "product.updated"
                                ],
                                "headers": {
                                    "X-Api-Key": "abc"
                                },
                                "is_active": true,
                                "timeout_seconds": 15
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `webhook`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "webhook": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/available-events": {
            "get": {
                "operationId": "get_api_webhooks_available_events",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "List subscribable events",
                "description": "The event names a webhook can subscribe to (e.g. `sale.created`, `sale.updated`, `purchase.created`, `product.updated`, `stock.low`, `customer.created`), each with a short description.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@availableEvents",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L157-L161",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`events[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "events": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/deliveries": {
            "get": {
                "operationId": "get_api_webhooks_deliveries",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "List deliveries (all webhooks)",
                "description": "Paginated delivery attempts across all webhooks: event, URL, response status, duration, attempt number and error. Filter by `webhook_id`, `status`, `event`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@deliveries",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L163-L199",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "WebhookDelivery"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "event",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Event name."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `success`, `failed`."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`deliveries[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "deliveries": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/deliveries/{id}": {
            "get": {
                "operationId": "get_api_webhooks_deliveries_id",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Get a delivery",
                "description": "Payload, response code/body, attempts.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@deliveryShow",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L201-L206",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "WebhookDelivery"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Delivery id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`delivery`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "delivery": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/incoming-logs": {
            "get": {
                "operationId": "get_api_webhooks_incoming_logs",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "List incoming webhook logs",
                "description": "Paginated log of requests received on `POST /api/webhooks/incoming/{source}` with source, signature result, processing status and payload size.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@incomingLogs",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L208-L237",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "WebhookIncomingLog"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "source",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Source key."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Processing status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`logs[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "logs": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/incoming-logs/{id}": {
            "get": {
                "operationId": "get_api_webhooks_incoming_logs_id",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Get an incoming webhook log",
                "description": "One incoming log entry with headers, raw payload and processing result.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@incomingLogShow",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L239-L244",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "WebhookIncomingLog"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Log id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`log`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "log": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/incoming/{source}": {
            "post": {
                "operationId": "post_api_webhooks_incoming_source",
                "tags": [
                    "Incoming Webhooks"
                ],
                "summary": "Receive an incoming webhook",
                "description": "Public. Logs the request, validates the signature configured for `source` and processes it. Body is provider-specific JSON.",
                "x-section": "Integrations",
                "x-surface": "public",
                "x-public": true,
                "x-controller": "Webhooks\\IncomingWebhooksController@handle",
                "x-source": "app/Http/Controllers/Webhooks/IncomingWebhooksController.php#L15-L28",
                "x-middleware": [
                    "api"
                ],
                "parameters": [
                    {
                        "name": "source",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Source key (e.g. `shopify`, `custom`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success`, `log_id`, `status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "log_id": {},
                                        "status": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid signature.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid signature"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/api/webhooks/{id}/deliveries": {
            "get": {
                "operationId": "get_api_webhooks_id_deliveries",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "List deliveries of a webhook",
                "description": "Delivery attempts of one webhook, newest first.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@deliveries",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L163-L199",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "viewAny",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "WebhookDelivery"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Webhook id."
                    },
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    },
                    {
                        "name": "event",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Event."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`deliveries[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "deliveries": {
                                            "type": "integer"
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/{id}/regenerate-secret": {
            "post": {
                "operationId": "post_api_webhooks_id_regenerate_secret",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Regenerate the signing secret",
                "description": "Generates a new signing secret and returns it once. Update the receiver before the next event fires.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@regenerateSecret",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L119-L125",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "webhooks_edit",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "Webhook"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Webhook id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and new `secret`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "secret": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/{id}/test": {
            "post": {
                "operationId": "post_api_webhooks_id_test",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Send a test delivery",
                "description": "Dispatches a `webhook.test` event and returns the delivery id to inspect.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@test",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L127-L155",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "webhooks_edit",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "Webhook",
                    "WebhookDelivery"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Webhook id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `delivery_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "delivery_id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/{id}/toggle": {
            "post": {
                "operationId": "post_api_webhooks_id_toggle",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Enable / disable a webhook",
                "description": "Enables or disables the webhook. Disabled webhooks receive no deliveries.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@toggle",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L111-L117",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "webhooks_edit",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "Webhook"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Webhook id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `is_active`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "is_active": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/webhooks/{webhook}": {
            "delete": {
                "operationId": "delete_api_webhooks_webhook",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Delete a webhook",
                "description": "Deletes a webhook and its delivery history.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@destroy",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L103-L109",
                "x-route-name": "webhooks.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "webhooks_delete",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "Webhook"
                ],
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Webhook id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_webhooks_webhook",
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Get a webhook",
                "description": "One webhook with its events, headers, timeout, secret (masked), status and delivery statistics.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@show",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L75-L80",
                "x-route-name": "webhooks.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "webhooks_view",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "Webhook"
                ],
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Webhook id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`webhook`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "webhook": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_webhooks_webhook",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Update a webhook",
                "description": "Updates the URL, events, headers, timeout or active flag.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@update",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L82-L101",
                "x-route-name": "webhooks.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "webhooks_edit",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "Webhook"
                ],
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Webhook id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "events": {
                                        "minItems": 1,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Events.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "headers": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Headers.",
                                        "type": "object"
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "timeout_seconds": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Timeout."
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 2048,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "url",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "URL."
                                    }
                                },
                                "required": [
                                    "events",
                                    "name",
                                    "url"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `webhook`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "webhook": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_webhooks_webhook",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Outgoing Webhooks"
                ],
                "summary": "Update a webhook",
                "description": "Updates the URL, events, headers, timeout or active flag.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Webhooks\\WebhooksController@update",
                "x-source": "app/Http/Controllers/Webhooks/WebhooksController.php#L82-L101",
                "x-route-name": "webhooks.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "webhooks_edit",
                        "policy": "WebhookPolicy"
                    }
                ],
                "x-models": [
                    "Webhook"
                ],
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Webhook id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "events": {
                                        "minItems": 1,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Events.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "headers": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Headers.",
                                        "type": "object"
                                    },
                                    "is_active": {
                                        "type": "boolean",
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Active."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "timeout_seconds": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "min:1",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Timeout."
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "maxLength": 2048,
                                        "x-conditional": [
                                            "sometimes"
                                        ],
                                        "x-laravel-rules": [
                                            "sometimes",
                                            "required",
                                            "url",
                                            "max:2048"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "URL."
                                    }
                                },
                                "required": [
                                    "events",
                                    "name",
                                    "url"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `webhook`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "webhook": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/woo-sync/latest": {
            "get": {
                "operationId": "get_api_woo_sync_latest",
                "tags": [
                    "Sync Jobs"
                ],
                "summary": "Latest running sync job",
                "description": "The caller's most recent job in `pending` / `running` / `cancelling`, or `null`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "SyncJobController@latest",
                "x-source": "app/Http/Controllers/SyncJobController.php#L33-L57",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SyncJob"
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `job`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "job": {
                                            "type": "object",
                                            "properties": {
                                                "id": {},
                                                "status": {}
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woo-sync/status/{id}": {
            "get": {
                "operationId": "get_api_woo_sync_status_id",
                "tags": [
                    "Sync Jobs"
                ],
                "summary": "Sync job status (alias)",
                "description": "GET /api/sync/status/{id} /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "SyncJobController@status",
                "x-source": "app/Http/Controllers/SyncJobController.php#L62-L135",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SyncJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Job status object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "status": {},
                                        "total_items": {
                                            "type": "integer"
                                        },
                                        "processed_items": {
                                            "type": "integer"
                                        },
                                        "success_items": {
                                            "type": "integer"
                                        },
                                        "failed_items": {
                                            "type": "integer"
                                        },
                                        "percentage": {
                                            "type": "integer"
                                        },
                                        "stage": {},
                                        "current_product_id": {},
                                        "current_sku": {},
                                        "last_error": {},
                                        "cancel_requested": {
                                            "type": "boolean"
                                        },
                                        "stuck": {},
                                        "worker_heartbeat_at": {
                                            "type": "string"
                                        },
                                        "started_at": {
                                            "type": "string"
                                        },
                                        "finished_at": {
                                            "type": "string"
                                        },
                                        "updated_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woo-sync/{id}/cancel": {
            "post": {
                "operationId": "post_api_woo_sync_id_cancel",
                "tags": [
                    "Sync Jobs"
                ],
                "summary": "Cancel a sync job (alias)",
                "description": "POST /api/sync/{id}/cancel /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "SyncJobController@cancel",
                "x-source": "app/Http/Controllers/SyncJobController.php#L140-L154",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "SyncJob"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Job id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/brands/pull-stats": {
            "get": {
                "operationId": "get_api_woocommerce_brands_pull_stats",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Brand import statistics",
                "description": "GET /api/woocommerce/brands/pull-stats Get stats for WooCommerce → Stocky brands: total in WooCommerce, imported (Stocky brands with woocommerce_id), not imported /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getBrandsPullStats",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1154-L1183",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Brand",
                    "WooCommerceSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`total_woo`, `imported`, `not_imported`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total_woo": {},
                                        "imported": {},
                                        "not_imported": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/brands/unsynced-count": {
            "get": {
                "operationId": "get_api_woocommerce_brands_unsynced_count",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Unmapped brands count",
                "description": "Number of Stocky brands with no WooCommerce mapping.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@unsyncedBrandsCount",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L930-L936",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Brand"
                ],
                "responses": {
                    "200": {
                        "description": "`count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/categories/map": {
            "post": {
                "operationId": "post_api_woocommerce_categories_map",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Map categories manually",
                "description": "POST /woocommerce/categories/map Body: { mappings: [ { id: <local_category_id>, woocommerce_id: <int|null> }, ... ] } /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@mapCategories",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1749-L1769",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "mappings": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "integer",
                                                    "x-exists": "categories,id",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer",
                                                        "exists:categories,id"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Stocky category id."
                                                },
                                                "woocommerce_id": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer",
                                                        "min:0"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Woo category id (null to unmap)."
                                                }
                                            },
                                            "required": [
                                                "id"
                                            ]
                                        },
                                        "x-laravel-rules": [
                                            "required",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Pairs."
                                    }
                                },
                                "required": [
                                    "mappings"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/categories/pull-stats": {
            "get": {
                "operationId": "get_api_woocommerce_categories_pull_stats",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Category import statistics",
                "description": "GET /api/woocommerce/categories/pull-stats Get stats for WooCommerce → Stocky categories: total in WooCommerce, imported (Stocky categories with woocommerce_id), not imported /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getCategoriesPullStats",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1118-L1148",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Category",
                    "WooCommerceSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`total_woo`, `imported`, `not_imported`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total_woo": {},
                                        "imported": {},
                                        "not_imported": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/categories/unsynced-count": {
            "get": {
                "operationId": "get_api_woocommerce_categories_unsynced_count",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Unmapped categories count",
                "description": "Number of Stocky categories with no WooCommerce mapping.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@unsyncedCategoriesCount",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L922-L928",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Category"
                ],
                "responses": {
                    "200": {
                        "description": "`count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/customers": {
            "get": {
                "operationId": "get_api_woocommerce_customers",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Browse WooCommerce customers",
                "description": "GET /api/woocommerce/customers Fetch WooCommerce customers with pagination /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getWooCommerceCustomers",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1311-L1390",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Page."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`customers[]`, `totalRows`, `currentPage`, `perPage`, `totalPages`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Failed to fetch WooCommerce customers"
                                        },
                                        "status": {},
                                        "customers": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "currentPage": {
                                            "type": "integer"
                                        },
                                        "perPage": {
                                            "type": "integer"
                                        },
                                        "totalPages": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/customers/stats": {
            "get": {
                "operationId": "get_api_woocommerce_customers_stats",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Customer sync counts",
                "description": "GET /api/woocommerce/customers/stats Get customer statistics: total, synced (with woocommerce_id), unsynced /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getCustomersStats",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L953-L976",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "responses": {
                    "200": {
                        "description": "`total`, `synced`, `unsynced`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "synced": {},
                                        "unsynced": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/customers/sync-issues": {
            "get": {
                "operationId": "get_api_woocommerce_customers_sync_issues",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Customers with sync issues",
                "description": "GET /api/woocommerce/customers/sync-issues List Stocky clients that have a sync issue recorded. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getCustomerSyncIssues",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1638-L1701",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`issues[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "name": {},
                                        "email": {},
                                        "phone": {},
                                        "woocommerce_id": {},
                                        "sync_issue_type": {},
                                        "sync_issue_message": {},
                                        "sync_issue_source": {},
                                        "sync_issue_at": {},
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "issues": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/customers/sync-issues/{id}/link": {
            "post": {
                "operationId": "post_api_woocommerce_customers_sync_issues_id_link",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Link a customer to a Woo customer",
                "description": "POST /api/woocommerce/customers/sync-issues/{id}/link Body: { woocommerce_id: int } Manually links a Stocky client to a WooCommerce customer ID and clears the issue. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@manualLinkCustomerSyncIssue",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1726-L1743",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "woocommerce_id": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "WooCommerce customer id."
                                    }
                                },
                                "required": [
                                    "woocommerce_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/customers/sync-issues/{id}/resolve": {
            "post": {
                "operationId": "post_api_woocommerce_customers_sync_issues_id_resolve",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Clear a customer sync issue",
                "description": "POST /api/woocommerce/customers/sync-issues/{id}/resolve Clears the issue fields for a Stocky client. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@resolveCustomerSyncIssue",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1707-L1719",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Customer id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/customers/unsynced-count": {
            "get": {
                "operationId": "get_api_woocommerce_customers_unsynced_count",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Unmapped customers count",
                "description": "GET /api/woocommerce/customers/unsynced-count /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@unsyncedCustomersCount",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L941-L947",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Client"
                ],
                "responses": {
                    "200": {
                        "description": "`count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/logs": {
            "delete": {
                "operationId": "delete_api_woocommerce_logs",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Clear WooCommerce logs",
                "description": "DELETE /woocommerce/logs Clear WooCommerce sync logs. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@clearLogs",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L748-L754",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_woocommerce_logs",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "WooCommerce logs",
                "description": "Last 200 log rows.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@logs",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L735-L742",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceLog"
                ],
                "responses": {
                    "200": {
                        "description": "`data[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/orders": {
            "get": {
                "operationId": "get_api_woocommerce_orders",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Browse WooCommerce orders",
                "description": "GET /api/woocommerce/orders Fetch WooCommerce orders with pagination /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getWooCommerceOrders",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1396-L1534",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting",
                    "Sale"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Page."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`orders[]` (with import status), `totalRows`, paging.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Failed to fetch WooCommerce orders"
                                        },
                                        "status": {},
                                        "orders": {},
                                        "totalRows": {
                                            "type": "integer"
                                        },
                                        "currentPage": {
                                            "type": "integer"
                                        },
                                        "perPage": {
                                            "type": "integer"
                                        },
                                        "totalPages": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/orders/imported": {
            "get": {
                "operationId": "get_api_woocommerce_orders_imported",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Sales imported from WooCommerce",
                "description": "Sortable `id, date, Ref, GrandTotal, payment_statut, statut, woocommerce_order_id, woocommerce_order_status`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getImportedWooOrders",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1540-L1607",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "Sale"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/SortField"
                    },
                    {
                        "$ref": "#/components/parameters/SortType"
                    },
                    {
                        "$ref": "#/components/parameters/search"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`orders[]` and `totalRows`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "orders": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "totalRows": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/orders/imported/stats": {
            "get": {
                "operationId": "get_api_woocommerce_orders_imported_stats",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Imported order counts",
                "description": "GET /api/woocommerce/orders/imported/stats /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getImportedWooOrdersStats",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1612-L1632",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Sale"
                ],
                "responses": {
                    "200": {
                        "description": "`total_imported`, `imported_today`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total_imported": {},
                                        "imported_today": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/products/auto-link": {
            "post": {
                "operationId": "post_api_woocommerce_products_auto_link",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Auto-link products by SKU",
                "description": "Maps Stocky products / variants to Woo products / variations whose SKU matches exactly and uniquely.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@autoLinkProductsBySku",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1779-L1989",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting",
                    "Product",
                    "ProductVariant",
                    "WooCommerceLog"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`, `products`, `variants`, `samples`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "products": {
                                            "type": "object",
                                            "properties": {
                                                "scanned": {
                                                    "type": "integer"
                                                },
                                                "linked": {},
                                                "ambiguous": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "no_match": {}
                                            }
                                        },
                                        "variants": {
                                            "type": "object",
                                            "properties": {
                                                "linked": {},
                                                "ambiguous": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "no_match": {}
                                            }
                                        },
                                        "samples": {
                                            "type": "object",
                                            "properties": {
                                                "ambiguous": {
                                                    "type": "array",
                                                    "items": {}
                                                },
                                                "no_match": {
                                                    "type": "array",
                                                    "items": {}
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/products/fix-categories": {
            "post": {
                "operationId": "post_api_woocommerce_products_fix_categories",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Re-apply categories on Woo products",
                "description": "POST /api/woocommerce/products/fix-categories Fix Woo products that became \"Uncategorized\" by re-applying mapped categories. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@fixProductCategories",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L842-L855",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "responses": {
                    "200": {
                        "description": "Result.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/products/pull-stats": {
            "get": {
                "operationId": "get_api_woocommerce_products_pull_stats",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Product import statistics",
                "description": "GET /api/woocommerce/products/pull-stats Get stats for WooCommerce → Stocky: total in WooCommerce, imported (Stocky products with woocommerce_id), not imported /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getProductsPullStats",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L982-L1112",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "WooCommerceSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`total_woo`, `imported`, `not_imported`, breakdowns by type.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "total_woo": {},
                                        "total_woo_all": {},
                                        "total_woo_variations": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "total_woo_by_type": {},
                                        "total_woo_by_type_breakdown": {},
                                        "imported": {},
                                        "not_imported": {},
                                        "sample_missing_ids": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/products/unmapped-report": {
            "get": {
                "operationId": "get_api_woocommerce_products_unmapped_report",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Unmapped items report",
                "description": "Unlinked products, unlinked variants and the Woo line items from recent failed order imports.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getUnmappedItemsReport",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1999-L2084",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Product",
                    "ProductVariant",
                    "WooCommerceLog"
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Rows per list (default 50, max 500)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`unlinked_products`, `unlinked_variants`, `order_failures[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "unlinked_products": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "sample": {
                                                    "type": "array",
                                                    "items": {}
                                                }
                                            }
                                        },
                                        "unlinked_variants": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "sample": {
                                                    "type": "array",
                                                    "items": {}
                                                }
                                            }
                                        },
                                        "order_failures": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/reset-brands-sync": {
            "post": {
                "operationId": "post_api_woocommerce_reset_brands_sync",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Reset brand mappings",
                "description": "POST /woocommerce/reset-brands-sync Reset sync state for brands only. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@resetBrandsSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L880-L893",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/reset-categories-sync": {
            "post": {
                "operationId": "post_api_woocommerce_reset_categories_sync",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Reset category mappings",
                "description": "POST /woocommerce/reset-categories-sync Reset sync state for categories only. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@resetCategoriesSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L861-L874",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/reset-customers-sync": {
            "post": {
                "operationId": "post_api_woocommerce_reset_customers_sync",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Reset customer mappings",
                "description": "POST /woocommerce/reset-customers-sync /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@resetCustomersSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1293-L1305",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/reset-products-sync": {
            "post": {
                "operationId": "post_api_woocommerce_reset_products_sync",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Reset product mappings",
                "description": "POST /woocommerce/reset-products-sync Reset sync state for products and variants only. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@resetProductsSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L812-L836",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/reset-stock-sync": {
            "post": {
                "operationId": "post_api_woocommerce_reset_stock_sync",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Clear stock sync logs",
                "description": "POST /woocommerce/reset-stock-sync Reset sync state for stock (clears stock-related logs). /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@resetStockSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L899-L911",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/reset-sync": {
            "post": {
                "operationId": "post_api_woocommerce_reset_sync",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Reset all sync state",
                "description": "Cancels running product syncs, clears product/variant/category mappings, logs and last sync time.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@resetSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L760-L806",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceLog",
                    "WooCommerceSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/settings": {
            "get": {
                "operationId": "get_api_woocommerce_settings",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Get WooCommerce settings",
                "description": "Current WooCommerce settings (store URL, consumer key/secret masked, default warehouse/customer, sync options).",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@getSettings",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L164-L175",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`settings`, effective `sync_options` and `sync_options_meta` (field descriptors).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sync_options": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sync_options_meta": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_woocommerce_settings",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Save WooCommerce settings",
                "description": "Changing the store URL resets the sync state. `sync_options` holds tuning values (batch sizes, stuck timeout, …) described by `sync_options_meta`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@saveSettings",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L177-L259",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "consumer_key": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "REST consumer key."
                                    },
                                    "consumer_secret": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "REST consumer secret."
                                    },
                                    "store_url": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Shop URL."
                                    },
                                    "sync_interval": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Scheduled sync interval."
                                    },
                                    "sync_options": {
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "array"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Tuning options `{key: value}`.",
                                        "type": "object"
                                    },
                                    "wp_app_password": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "WordPress application password."
                                    },
                                    "wp_username": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "WordPress user (media uploads)."
                                    }
                                },
                                "required": [
                                    "consumer_key",
                                    "consumer_secret",
                                    "store_url"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `settings`, `sync_options`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "settings": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "sync_options": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/stock-metrics": {
            "get": {
                "operationId": "get_api_woocommerce_stock_metrics",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Stock metrics",
                "description": "GET /api/woocommerce/stock-metrics /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@stockMetrics",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L667-L689",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`in_stock`, `out_stock`, `last_sync`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "in_stock": {},
                                        "out_stock": {},
                                        "last_sync": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync-products/progress": {
            "get": {
                "operationId": "get_api_woocommerce_sync_products_progress",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Product sync progress (alias)",
                "description": "GET /api/woocommerce/sync/products/progress?token=... /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncProductsProgress",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L606-L662",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Progress token."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `state`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {},
                                        "state": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Missing token"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync-stock": {
            "post": {
                "operationId": "post_api_woocommerce_sync_stock",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Start a stock sync (alias)",
                "description": "Older alias of `POST /api/woocommerce/sync/stock`: starts a background stock push for mapped products.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncStock",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L455-L490",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting",
                    "Product"
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `token`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "token": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync-stock/progress": {
            "get": {
                "operationId": "get_api_woocommerce_sync_stock_progress",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Stock sync progress (alias)",
                "description": "GET /api/woocommerce/sync-stock/progress?token=... /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncStockProgress",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L547-L601",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Progress token."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `state`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {},
                                        "state": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Missing token"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/brands": {
            "post": {
                "operationId": "post_api_woocommerce_sync_brands",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Sync brands",
                "description": "Creates missing brands in WooCommerce and stores the mappings.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncBrands",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L713-L733",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`push` or `pull`."
                                    },
                                    "only_unsynced": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push only unmapped brands.",
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok` and `result`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "result": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/categories": {
            "post": {
                "operationId": "post_api_woocommerce_sync_categories",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Sync categories",
                "description": "Creates missing categories in WooCommerce and stores the mappings.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncCategories",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L691-L711",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`push` (default) or `pull`."
                                    },
                                    "only_unsynced": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push only unmapped categories.",
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok` and `result`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "result": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/customers": {
            "post": {
                "operationId": "post_api_woocommerce_sync_customers",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Sync customers",
                "description": "POST /api/woocommerce/sync/customers Query params: mode=push|pull (default: push), only_unsynced=true|false (for push mode), customer_id=int (for single customer sync) /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncCustomers",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1189-L1232",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "customer_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Sync a single customer."
                                    },
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`push` or `pull`."
                                    },
                                    "only_unsynced": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Push only unmapped customers.",
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok` and `result`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "result": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/orders": {
            "post": {
                "operationId": "post_api_woocommerce_sync_orders",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Pull orders into sales",
                "description": "Imports WooCommerce orders as sales in the default warehouse (or a single order with `order_id`). Orders with unmapped products fail — see *Unmapped items report*.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncOrders",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L1238-L1288",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting",
                    "Setting",
                    "Warehouse",
                    "UserWarehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "order_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Import one specific order."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Result with `imported`, `skipped`, `failed`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/products": {
            "post": {
                "operationId": "post_api_woocommerce_sync_products",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Start a product sync",
                "description": "Queues a background job and returns a progress `token` (poll *Product sync progress*). `mode=push` sends Stocky products to Woo; `mode=pull` imports Woo products.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncProducts",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L292-L433",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting",
                    "SyncJob",
                    "Product"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "mode": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "`push` (default) or `pull`."
                                    },
                                    "only_unsynced": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Skip already-mapped products.",
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `token`, `sync_job_id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "token": {
                                            "type": "string"
                                        },
                                        "sync_job_id": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/products/progress": {
            "get": {
                "operationId": "get_api_woocommerce_sync_products_progress_778f11",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Product sync progress",
                "description": "Progress `state` for a token; drains queued batches inline when no worker is running and flags stuck jobs.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncProductsProgress",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L606-L662",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Progress token."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `state`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {},
                                        "state": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Missing token"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/products/stop": {
            "post": {
                "operationId": "post_api_woocommerce_sync_products_stop",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Stop a product sync",
                "description": "POST /api/woocommerce/sync/products/stop Body: { token: string } Signals the queue job to cancel ASAP and marks the progress state as cancelled. /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@stopProductsSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L133-L162",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceLog"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "token": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Progress token."
                                    }
                                },
                                "required": [
                                    "token"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/stock": {
            "post": {
                "operationId": "post_api_woocommerce_sync_stock_b04256",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Start a stock sync",
                "description": "Pushes stock quantities of mapped products; returns a progress `token`.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncStock",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L455-L490",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting",
                    "Product"
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `token`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "token": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "WooCommerce not configured"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/stock/progress": {
            "get": {
                "operationId": "get_api_woocommerce_sync_stock_progress_0796a1",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Stock sync progress",
                "description": "GET /api/woocommerce/sync-stock/progress?token=... /",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@syncStockProgress",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L547-L601",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Progress token."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `state`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {},
                                        "state": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Missing token"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/sync/stock/stop": {
            "post": {
                "operationId": "post_api_woocommerce_sync_stock_stop",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Stop a stock sync",
                "description": "Requests cancellation of the running stock sync; the current batch finishes first.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@stopStockSync",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L492-L533",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "token": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Progress token."
                                    }
                                },
                                "required": [
                                    "token"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/test-connection": {
            "post": {
                "operationId": "post_api_woocommerce_test_connection",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Test the WooCommerce connection",
                "description": "Calls the WooCommerce REST API with the stored keys and reports success or the error.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@connectStore",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L261-L290",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "WooCommerceSetting",
                    "WooCommerceLog"
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and store info.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not configured / failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Missing WooCommerce credentials"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/woocommerce/unsynced-count": {
            "get": {
                "operationId": "get_api_woocommerce_unsynced_count",
                "tags": [
                    "WooCommerce"
                ],
                "summary": "Unmapped products count",
                "description": "Number of Stocky products with no WooCommerce mapping.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "WooCommerceSyncController@unsyncedCount",
                "x-source": "app/Http/Controllers/WooCommerceSyncController.php#L913-L920",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "slug": "woocommerce_settings",
                        "policy": "WooCommerceSettingPolicy"
                    }
                ],
                "x-models": [
                    "Product"
                ],
                "responses": {
                    "200": {
                        "description": "`count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/work_experience": {
            "get": {
                "operationId": "get_api_work_experience",
                "tags": [
                    "Employee Experience"
                ],
                "summary": "List work experience (not implemented)",
                "description": "**Not implemented** — use *Work experience of an employee*.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeExperienceController@index",
                "x-source": "app/Http/Controllers/hrm/EmployeeExperienceController.php#L13-L16",
                "x-route-name": "work_experience.index",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_work_experience",
                "tags": [
                    "Employee Experience"
                ],
                "summary": "Add a work experience entry",
                "description": "Adds a previous-employment entry to an employee (company, position, start/end dates, description).",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeExperienceController@store",
                "x-source": "app/Http/Controllers/hrm/EmployeeExperienceController.php#L20-L44",
                "x-route-name": "work_experience.store",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "create",
                        "slug": "add_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "EmployeeExperience"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employer."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "employment_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type (e.g. `Full Time`)."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End date."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start date."
                                    },
                                    "title": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Job title."
                                    }
                                },
                                "required": [
                                    "company_name",
                                    "employment_type",
                                    "end_date",
                                    "start_date",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/work_experience/{work_experience}": {
            "delete": {
                "operationId": "delete_api_work_experience_work_experience",
                "tags": [
                    "Employee Experience"
                ],
                "summary": "Delete a work experience entry",
                "description": "Deletes a work-experience entry.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeExperienceController@destroy",
                "x-source": "app/Http/Controllers/hrm/EmployeeExperienceController.php#L84-L93",
                "x-route-name": "work_experience.destroy",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "delete",
                        "slug": "delete_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "EmployeeExperience"
                ],
                "parameters": [
                    {
                        "name": "work_experience",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Entry id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_work_experience_work_experience",
                "tags": [
                    "Employee Experience"
                ],
                "summary": "Get a work experience entry (not implemented)",
                "description": "**Not implemented** — empty response.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeExperienceController@show",
                "x-source": "app/Http/Controllers/hrm/EmployeeExperienceController.php#L48-L52",
                "x-route-name": "work_experience.show",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "parameters": [
                    {
                        "name": "work_experience",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Entry id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "put": {
                "operationId": "put_api_work_experience_work_experience",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Employee Experience"
                ],
                "summary": "Update a work experience entry",
                "description": "Updates a work-experience entry.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeExperienceController@update",
                "x-source": "app/Http/Controllers/hrm/EmployeeExperienceController.php#L56-L80",
                "x-route-name": "work_experience.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "EmployeeExperience"
                ],
                "parameters": [
                    {
                        "name": "work_experience",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Entry id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employer."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "employment_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End date."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start date."
                                    },
                                    "title": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Job title."
                                    }
                                },
                                "required": [
                                    "company_name",
                                    "employment_type",
                                    "end_date",
                                    "start_date",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "patch": {
                "operationId": "patch_api_work_experience_work_experience",
                "x-methods": [
                    "PUT",
                    "PATCH"
                ],
                "tags": [
                    "Employee Experience"
                ],
                "summary": "Update a work experience entry",
                "description": "Updates a work-experience entry.",
                "x-section": "Human Resources",
                "x-surface": "admin",
                "x-controller": "hrm\\EmployeeExperienceController@update",
                "x-source": "app/Http/Controllers/hrm/EmployeeExperienceController.php#L56-L80",
                "x-route-name": "work_experience.update",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "slug": "edit_employee",
                        "policy": "EmployeePolicy"
                    }
                ],
                "x-models": [
                    "EmployeeExperience"
                ],
                "parameters": [
                    {
                        "name": "work_experience",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Entry id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company_name": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Employer."
                                    },
                                    "description": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Description."
                                    },
                                    "employee_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Employee."
                                    },
                                    "employment_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Type."
                                    },
                                    "end_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "End date."
                                    },
                                    "location": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Location."
                                    },
                                    "start_date": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "format": "date",
                                        "x-laravel-rules": [
                                            "required"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Start date."
                                    },
                                    "title": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Job title."
                                    }
                                },
                                "required": [
                                    "company_name",
                                    "employment_type",
                                    "end_date",
                                    "start_date",
                                    "title"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ],
                "x-alias-of": "put"
            }
        },
        "/api/xero/disconnect": {
            "post": {
                "operationId": "post_api_xero_disconnect",
                "tags": [
                    "Xero"
                ],
                "summary": "Disconnect Xero",
                "description": "Drop the token pair and organisation; app credentials stay.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@disconnect",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L77-L94",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "x-models": [
                    "XeroSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/xero/logs": {
            "delete": {
                "operationId": "delete_api_xero_logs",
                "tags": [
                    "Xero"
                ],
                "summary": "Clear Xero logs",
                "description": "Clears the Xero sync log.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@clearLogs",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L175-L182",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "x-models": [
                    "XeroLog"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "get": {
                "operationId": "get_api_xero_logs",
                "tags": [
                    "Xero"
                ],
                "summary": "Xero sync logs",
                "description": "Paginated Xero sync log entries.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@logs",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L163-L173",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "XeroLog"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Level."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/xero/reset-mappings": {
            "post": {
                "operationId": "post_api_xero_reset_mappings",
                "tags": [
                    "Xero"
                ],
                "summary": "Reset Xero mappings",
                "description": "Deletes contact/invoice/account mappings so the next sync re-creates them.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@resetMappings",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L124-L133",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entity_type": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "contact",
                                            "invoice",
                                            "payment"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "in:contact,invoice,payment"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`contact`, `invoice` or `payment`."
                                    }
                                },
                                "required": [
                                    "entity_type"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success` and `deleted`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "deleted": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/xero/settings": {
            "get": {
                "operationId": "get_api_xero_settings",
                "tags": [
                    "Xero"
                ],
                "summary": "Get Xero settings",
                "description": "Current Xero settings (client ID, connection status, tenant, account mappings); secrets are masked.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@settings",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L19-L38",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "x-models": [
                    "XeroSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`enabled`, `connected`, `client_id`, `has_client_secret`, `tenant_name`, account codes, `auto_sync`, `last_sync_at`, `connect_url`, `callback_url`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean"
                                        },
                                        "connected": {},
                                        "client_id": {},
                                        "has_client_secret": {},
                                        "tenant_name": {},
                                        "sales_account_code": {},
                                        "payment_account_code": {},
                                        "auto_sync": {
                                            "type": "boolean"
                                        },
                                        "last_sync_at": {
                                            "type": "string"
                                        },
                                        "connect_url": {
                                            "type": "string"
                                        },
                                        "callback_url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_xero_settings",
                "tags": [
                    "Xero"
                ],
                "summary": "Save Xero settings",
                "description": "Saves the Xero OAuth client credentials and the account codes used for sales, tax and payments.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@saveSettings",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L40-L74",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "x-models": [
                    "XeroSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "auto_sync": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Sync automatically."
                                    },
                                    "client_id": {
                                        "type": "string",
                                        "maxLength": 191,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:191"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "OAuth client id."
                                    },
                                    "client_secret": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "OAuth client secret (write-only)."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "required",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable."
                                    },
                                    "payment_account_code": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Xero bank account code for payments."
                                    },
                                    "sales_account_code": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:20"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Xero sales account code."
                                    }
                                },
                                "required": [
                                    "enabled"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`{ \"success\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/xero/stats": {
            "get": {
                "operationId": "get_api_xero_stats",
                "tags": [
                    "Xero"
                ],
                "summary": "Sync statistics",
                "description": "Counters: contacts and invoices synced, failures, last sync.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@stats",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L117-L122",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Mapped counts per entity.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/xero/sync/contacts": {
            "post": {
                "operationId": "post_api_xero_sync_contacts",
                "tags": [
                    "Xero"
                ],
                "summary": "Push customers as Xero contacts",
                "description": "Pushes customers (and optionally suppliers) to Xero as contacts.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@syncContacts",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L135-L147",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call (default 25).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `pushed`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Error."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/xero/sync/invoices": {
            "post": {
                "operationId": "post_api_xero_sync_invoices",
                "tags": [
                    "Xero"
                ],
                "summary": "Push sales as Xero invoices",
                "description": "Pushes completed sales in the selected date range to Xero as ACCREC invoices.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@syncInvoices",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L149-L161",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "update",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "batch": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Rows per call (default 10).",
                                        "type": "integer"
                                    },
                                    "start_after_id": {
                                        "x-inferred": true,
                                        "type": "integer",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Resume after this id."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`ok`, `pushed`, `last_id`, `done`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Error."
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/xero/test-connection": {
            "post": {
                "operationId": "post_api_xero_test_connection",
                "tags": [
                    "Xero"
                ],
                "summary": "Test the Xero connection",
                "description": "Verifies the stored Xero connection and returns the organisation name.",
                "x-section": "Integrations",
                "x-surface": "admin",
                "x-controller": "Integrations\\XeroSyncController@testConnection",
                "x-source": "app/Http/Controllers/Integrations/XeroSyncController.php#L96-L115",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "view",
                        "policy": "XeroSettingPolicy"
                    }
                ],
                "x-models": [
                    "XeroSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`ok`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "description": "Not connected / failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "error": {
                                            "type": "string",
                                            "example": "Not connected"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/csr/regenerate": {
            "post": {
                "operationId": "post_api_zatca_csr_regenerate",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "Regenerate the CSR",
                "description": "Creates a new key pair and CSR, restarting onboarding.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@regenerateCsr",
                "x-source": "app/Http/Controllers/ZatcaController.php#L154-L170",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "ZatcaSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`success` and `settings`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "settings": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "Tables not migrated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "ZATCA tables are not migrated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Error message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/documents": {
            "get": {
                "operationId": "get_api_zatca_documents",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "List submitted documents",
                "description": "Laravel-paginated submission history (default 20 per page): `id, invoice_number, source (Sale#12), source_kind, source_id, type, subtype, uuid, icv, status, environment, warnings, errors, submitted_at`.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@documents",
                "x-source": "app/Http/Controllers/ZatcaController.php#L175-L205",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "x-paginated": true,
                "x-models": [
                    "ZatcaDocument"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/limit"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Filter on submission status (e.g. `cleared`, `reported`, `rejected`, `pending`)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginator object with `data[]`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "invoice_number": {},
                                        "source": {
                                            "type": "string"
                                        },
                                        "source_kind": {
                                            "type": "string"
                                        },
                                        "source_id": {},
                                        "type": {},
                                        "subtype": {},
                                        "uuid": {},
                                        "icv": {},
                                        "status": {},
                                        "environment": {},
                                        "warnings": {},
                                        "errors": {},
                                        "submitted_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/documents/{id}/xml": {
            "get": {
                "operationId": "get_api_zatca_documents_id_xml",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "Download a document's XML",
                "description": "Returns the cleared (or original) UBL XML of the submitted document as an `application/xml` attachment.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@downloadXml",
                "x-source": "app/Http/Controllers/ZatcaController.php#L210-L221",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "ZatcaDocument"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "ZATCA document id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "XML file."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/logs": {
            "get": {
                "operationId": "get_api_zatca_logs",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "List recent gateway calls",
                "description": "Most recent ZATCA API request/response logs (default 50) for troubleshooting.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@logs",
                "x-source": "app/Http/Controllers/ZatcaController.php#L243-L250",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "ZatcaLog"
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "integer",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Number of log rows (default 50)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of log rows.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/onboard": {
            "post": {
                "operationId": "post_api_zatca_onboard",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "Onboard with ZATCA",
                "description": "Runs the full onboarding: generates the key pair and CSR if missing, requests a compliance CSID with the one-time `otp` from the Fatoora portal, runs the compliance invoice checks and requests the production CSID. `status` becomes `ready` on success.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@onboard",
                "x-source": "app/Http/Controllers/ZatcaController.php#L126-L149",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "ZatcaSetting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "otp": {
                                        "type": "string",
                                        "minLength": 4,
                                        "maxLength": 12,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "min:4",
                                            "max:12"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "One-time password from the Fatoora portal (4–12 chars)."
                                    }
                                },
                                "required": [
                                    "otp"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `status`, `compliance_checks`, `settings`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "status": {},
                                        "compliance_checks": {},
                                        "settings": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "ZATCA tables not migrated.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "ZATCA tables are not migrated."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/sale_returns/{id}/submit": {
            "post": {
                "operationId": "post_api_zatca_sale_returns_id_submit",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "Submit or retry a credit note",
                "description": "Same as the sale submission but for a sale return, issued as a credit note referencing the original invoice.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@submitSaleReturn",
                "x-source": "app/Http/Controllers/ZatcaController.php#L235-L238",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale return id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success`, `status`, `qr`, `warnings`, `errors`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "status": {},
                                        "qr": {},
                                        "warnings": {},
                                        "errors": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Not configured / gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/sales/{id}/submit": {
            "post": {
                "operationId": "post_api_zatca_sales_id_submit",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "Submit or retry a sale invoice",
                "description": "Builds the UBL invoice for the sale, signs it and sends it for clearance/reporting. Returns the resulting `status`, the `qr` payload for the receipt and any `warnings` / `errors` from ZATCA.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@submitSale",
                "x-source": "app/Http/Controllers/ZatcaController.php#L226-L229",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Sale id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`success`, `status`, `qr`, `warnings`, `errors`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {},
                                        "status": {},
                                        "qr": {},
                                        "warnings": {},
                                        "errors": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Not configured / gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": false
                                        },
                                        "message": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/api/zatca/settings": {
            "get": {
                "operationId": "get_api_zatca_settings",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "Get ZATCA settings and onboarding state",
                "description": "Returns the phase 2 `settings` (organisation, address, environment, `onboarding_status`, compliance results, invoice counter — secrets are masked), the phase 1 `company` fields (`zatca_enabled`, `vat_number`, `name_ar`), the available `environments` and `phase2_available` (false when the ZATCA tables are not migrated).",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@settings",
                "x-source": "app/Http/Controllers/ZatcaController.php#L23-L49",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "ZatcaSetting",
                    "Setting"
                ],
                "responses": {
                    "200": {
                        "description": "`settings`, `company`, `environments[]`, `phase2_available`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "settings": {},
                                        "company": {},
                                        "environments": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "phase2_available": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            },
            "post": {
                "operationId": "post_api_zatca_settings",
                "tags": [
                    "ZATCA e-Invoicing"
                ],
                "summary": "Save ZATCA settings",
                "description": "Saves the phase 2 configuration and the phase 1 `company` block. Changing `environment` wipes the CSR, keys, CSIDs, counters and onboarding status — onboarding must be redone.",
                "x-section": "Finance",
                "x-surface": "admin",
                "x-controller": "ZatcaController@saveSettings",
                "x-source": "app/Http/Controllers/ZatcaController.php#L54-L121",
                "x-middleware": [
                    "api",
                    "auth:api",
                    "Is_Active",
                    "request.safety",
                    "token.timeout"
                ],
                "x-permission": [
                    {
                        "ability": "zatca_settings",
                        "slug": "zatca_settings",
                        "policy": "SalePolicy"
                    }
                ],
                "x-models": [
                    "ZatcaSetting",
                    "Setting"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "auto_submit": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Submit invoices automatically when a sale / return is saved."
                                    },
                                    "building_number": {
                                        "nullable": true,
                                        "x-rules": [
                                            "digits:4"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "digits:4"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "4-digit building number.",
                                        "type": "string"
                                    },
                                    "business_category": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Business category (industry)."
                                    },
                                    "city": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "City."
                                    },
                                    "common_name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "CSR common name."
                                    },
                                    "company": {
                                        "properties": {
                                            "name_ar": {
                                                "type": "string",
                                                "maxLength": 190,
                                                "nullable": true,
                                                "x-laravel-rules": [
                                                    "nullable",
                                                    "string",
                                                    "max:190"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Seller name in Arabic."
                                            },
                                            "vat_number": {
                                                "type": "string",
                                                "maxLength": 190,
                                                "nullable": true,
                                                "x-laravel-rules": [
                                                    "nullable",
                                                    "string",
                                                    "max:190"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Seller VAT number."
                                            },
                                            "zatca_enabled": {
                                                "type": "boolean",
                                                "nullable": true,
                                                "x-laravel-rules": [
                                                    "nullable",
                                                    "boolean"
                                                ],
                                                "x-sources": [
                                                    "validated"
                                                ],
                                                "description": "Print the ZATCA QR on receipts."
                                            }
                                        },
                                        "description": "Company identity for ZATCA as a nested object: legal name (English/Arabic), VAT number, CRN, address lines, building number, city, postal code and district.",
                                        "type": "object"
                                    },
                                    "crn": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Commercial registration number."
                                    },
                                    "enabled": {
                                        "type": "boolean",
                                        "x-laravel-rules": [
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Enable phase 2 submission."
                                    },
                                    "environment": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "enum": [
                                            "sandbox",
                                            "simulation",
                                            "production"
                                        ],
                                        "x-laravel-rules": [
                                            "in:sandbox,simulation,production"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "`sandbox`, `simulation` or `production`."
                                    },
                                    "invoice_types": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-rules": [
                                            "regex:/^[01]{4}$/"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "regex:/^[01]{4}$/"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "4-digit flags `TSCZ` for supported invoice types, e.g. `1100`."
                                    },
                                    "organization_name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Legal organisation name."
                                    },
                                    "organization_unit": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Organisation unit / branch."
                                    },
                                    "plot_identification": {
                                        "type": "string",
                                        "maxLength": 10,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:10"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Plot id (max 10)."
                                    },
                                    "postal_zone": {
                                        "nullable": true,
                                        "x-rules": [
                                            "digits:5"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "digits:5"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "5-digit postal code.",
                                        "type": "string"
                                    },
                                    "solution_name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Solution provider name."
                                    },
                                    "solution_version": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Solution version."
                                    },
                                    "street_name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Street."
                                    },
                                    "sub_division": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "District."
                                    },
                                    "zero_tax_reason": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default VAT exemption reason text."
                                    },
                                    "zero_tax_reason_code": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Default VAT exemption reason code."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "`success`, `phase2_available`, `settings`, `company`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "phase2_available": {
                                            "type": "boolean"
                                        },
                                        "settings": {},
                                        "company": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "BearerToken": []
                    },
                    {
                        "StockyCookie": []
                    }
                ]
            }
        },
        "/online_store/account": {
            "put": {
                "operationId": "put_online_store_account",
                "tags": [
                    "Customer Account"
                ],
                "summary": "Update account",
                "description": "Updates the store login (username, email, optional new password) and the linked client's name/email.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\AccountPagesController@update",
                "x-source": "app/Http/Controllers/Api/Store/AccountPagesController.php#L36-L72",
                "x-route-name": "account.update",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "Client"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "x-rules": [
                                            "dynamic:'unique:ecommerce_clients,email,' . $user->id"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "max:190",
                                            "dynamic:'unique:ecommerce_clients,email,' . $user->id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email (unique)."
                                    },
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "minLength": 6,
                                        "nullable": true,
                                        "x-rules": [
                                            "confirmed (send <field>_confirmation)"
                                        ],
                                        "x-laravel-rules": [
                                            "nullable",
                                            "confirmed",
                                            "min:6"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "New password (min 6, optional)."
                                    },
                                    "username": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Display name."
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "description": "Repeat the new password.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "required": [
                                    "email",
                                    "username"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/address": {
            "put": {
                "operationId": "put_online_store_account_address",
                "tags": [
                    "Customer Account"
                ],
                "summary": "Update address",
                "description": "Updates the shipping / billing address on the linked client. `name` is only changed when non-empty.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\AccountPagesController@updateAddress",
                "x-source": "app/Http/Controllers/Api/Store/AccountPagesController.php#L124-L161",
                "x-route-name": "account.address.update",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "Client"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "adresse": {
                                        "type": "string",
                                        "maxLength": 250,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:250"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Street address."
                                    },
                                    "city": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "City."
                                    },
                                    "country": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Country."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    },
                                    "state": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "State."
                                    },
                                    "zip": {
                                        "type": "string",
                                        "maxLength": 30,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:30"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Postal code."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/orders/{id}": {
            "get": {
                "operationId": "get_online_store_account_orders_id",
                "tags": [
                    "Customer Account"
                ],
                "summary": "Order detail page (HTML)",
                "description": "Renders the account order page; data is loaded from *Get one of my orders*.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-route-name": "account.order.show",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/orders/{id}/cancel": {
            "post": {
                "operationId": "post_online_store_account_orders_id_cancel",
                "tags": [
                    "My Returns"
                ],
                "summary": "Cancel an order",
                "description": "Pending unpaid orders are cancelled immediately; paid ones are refunded (status `refunded`) or queued as a `requested` cancellation depending on settings.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerReturnsController@cancel",
                "x-source": "app/Http/Controllers/Api/Store/CustomerReturnsController.php#L77-L96",
                "x-route-name": "account.order.cancel",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reason."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "201": {
                        "description": "`success`, `status`, `order_status`, `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {},
                                        "order_status": {},
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/orders/{id}/invoice": {
            "get": {
                "operationId": "get_online_store_account_orders_id_invoice",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "Download my order invoice (PDF)",
                "description": "GET /account/orders/{id}/invoice — customer downloads their own invoice. /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CheckoutController@invoice",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L1160-L1182",
                "x-route-name": "account.order.invoice",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-response-type": "file",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF file.",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/orders/{id}/return": {
            "post": {
                "operationId": "post_online_store_account_orders_id_return",
                "tags": [
                    "My Returns"
                ],
                "summary": "Request a return",
                "description": "POST /account/orders/{id}/return",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerReturnsController@requestReturn",
                "x-source": "app/Http/Controllers/Api/Store/CustomerReturnsController.php#L99-L123",
                "x-route-name": "account.order.return",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "online_order_item_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Order line id."
                                                },
                                                "qty": {
                                                    "type": "number",
                                                    "minimum": 0.001,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "numeric",
                                                        "min:0.001"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity to return."
                                                }
                                            },
                                            "required": [
                                                "online_order_item_id",
                                                "qty"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Lines to return."
                                    },
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reason."
                                    }
                                },
                                "required": [
                                    "items"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success`, `return_id`, `status`, `refund_amount`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "return_id": {},
                                        "status": {},
                                        "refund_amount": {
                                            "type": "number"
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/orders/{id}/return-eligibility": {
            "get": {
                "operationId": "get_online_store_account_orders_id_return_eligibility",
                "tags": [
                    "My Returns"
                ],
                "summary": "Can this order be cancelled / returned?",
                "description": "`can_cancel` (pending orders, when cancellations are allowed), `can_return` (delivered within the return window), `returnable_items` with remaining quantities, and `open_requests`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerReturnsController@eligibility",
                "x-source": "app/Http/Controllers/Api/Store/CustomerReturnsController.php#L62-L74",
                "x-route-name": "account.order.return.eligibility",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "can_cancel": {},
                                        "can_return": {},
                                        "returnable_items": {},
                                        "open_requests": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/orders/{id}/review": {
            "post": {
                "operationId": "post_online_store_account_orders_id_review",
                "tags": [
                    "Reviews & Questions"
                ],
                "summary": "Submit or update a review",
                "description": "One review per customer and product; auto-approved when the store enables it, otherwise `pending`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerReviewsController@submit",
                "x-source": "app/Http/Controllers/Api/Store/CustomerReviewsController.php#L68-L107",
                "x-route-name": "account.order.review",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "StoreSetting",
                    "Client",
                    "ProductReview"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "comment": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Comment (max 2000)."
                                    },
                                    "product_id": {
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product from the order."
                                    },
                                    "rating": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 5,
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "min:1",
                                            "max:5"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "1–5."
                                    }
                                },
                                "required": [
                                    "product_id",
                                    "rating"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success`, `status`, `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "status": {},
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/orders/{id}/reviewable": {
            "get": {
                "operationId": "get_online_store_account_orders_id_reviewable",
                "tags": [
                    "Reviews & Questions"
                ],
                "summary": "Items of my order I can review",
                "description": "Unique products of the order with `my_review` when already reviewed, plus `eligible` (order confirmed/delivered).",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerReviewsController@reviewable",
                "x-source": "app/Http/Controllers/Api/Store/CustomerReviewsController.php#L31-L65",
                "x-route-name": "account.order.reviewable",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "ProductReview"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product_id": {},
                                        "name": {},
                                        "my_review": {
                                            "type": "object"
                                        },
                                        "eligible": {},
                                        "order_status": {},
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/account/preferences": {
            "put": {
                "operationId": "put_online_store_account_preferences",
                "tags": [
                    "Customer Account"
                ],
                "summary": "Update language & currency preferences",
                "description": "Empty values fall back to the store defaults. Applied to the current session immediately.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\AccountPagesController@updatePreferences",
                "x-source": "app/Http/Controllers/Api/Store/AccountPagesController.php#L83-L118",
                "x-route-name": "account.preferences.update",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "preferred_currency_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "currencies,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:currencies,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Display currency id."
                                    },
                                    "preferred_locale": {
                                        "type": "string",
                                        "x-enum-source": "array_keys(store_locales())",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "in:array_keys(store_locales())"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Locale code from the store's enabled locales."
                                    }
                                }
                            }
                        }
                    },
                    "required": false
                },
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/collections/{slug}": {
            "get": {
                "operationId": "get_online_store_collections_slug",
                "tags": [
                    "Storefront Pages & Search"
                ],
                "summary": "Collection page",
                "description": "Redirects to the shop filtered by this collection.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreFrontController@collection",
                "x-source": "app/Http/Controllers/StoreFrontController.php#L631-L634",
                "x-route-name": "store.collection.show",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Collection slug."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/online_store/contact/send": {
            "post": {
                "operationId": "post_online_store_contact_send",
                "tags": [
                    "Contact Messages"
                ],
                "summary": "Submit the contact form (public)",
                "description": "Stores the message. `company` is a honeypot: when filled the request pretends to succeed without saving.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\MessageController@store",
                "x-source": "app/Http/Controllers/Api/Store/MessageController.php#L11-L31",
                "x-route-name": "store.contact.send",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "Message"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Honeypot — leave empty."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sender email."
                                    },
                                    "message": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Message body."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Sender name."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Subject."
                                    }
                                },
                                "required": [
                                    "email",
                                    "message",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok` and `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/currency/{id}": {
            "get": {
                "operationId": "get_online_store_currency_id",
                "tags": [
                    "Storefront Pages & Search"
                ],
                "summary": "Switch display currency",
                "description": "Stores the display currency in the session and redirects back.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-route-name": "store.currency.switch",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Currency id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/online_store/email/resend": {
            "post": {
                "operationId": "post_online_store_email_resend",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Resend verification email",
                "description": "Rate-limited (4/min). Same response whether or not the account exists.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@resendVerification",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L242-L258",
                "x-route-name": "store.verification.resend",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "throttle:4,1"
                ],
                "x-rate-limit": {
                    "requests": 4,
                    "per_minutes": 1
                },
                "x-models": [
                    "EcommerceClient",
                    "StoreSetting"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account email."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/email/verify/{id}/{hash}": {
            "get": {
                "operationId": "get_online_store_email_verify_id_hash",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Verify email (signed link)",
                "description": "Signed URL from the verification email. Marks the email verified and redirects to login (with a pending-approval notice when applicable).",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@verifyEmail",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L216-L239",
                "x-route-name": "store.verification.verify",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "throttle:12,1"
                ],
                "x-rate-limit": {
                    "requests": 12,
                    "per_minutes": 1
                },
                "x-models": [
                    "EcommerceClient",
                    "StoreSetting"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Store account id."
                    },
                    {
                        "name": "hash",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "SHA-1 of the email."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/online_store/forgot-password": {
            "post": {
                "operationId": "post_online_store_forgot_password",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Request a password reset link",
                "description": "Rate-limited (5/min). Emails a 60-minute reset link to verified, non-blocked accounts; the response never reveals whether the email exists.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@sendResetLink",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L294-L314",
                "x-route-name": "store.password.email",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "guest:store",
                    "throttle:5,1"
                ],
                "x-rate-limit": {
                    "requests": 5,
                    "per_minutes": 1
                },
                "x-models": [
                    "EcommerceClient",
                    "StoreSetting"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account email."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/garage/{id}": {
            "delete": {
                "operationId": "delete_online_store_garage_id",
                "tags": [
                    "My Garage"
                ],
                "summary": "Remove a garage vehicle",
                "description": "DELETE /garage/{id} — remove a saved vehicle.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreVehicleController@destroyGarage",
                "x-source": "app/Http/Controllers/StoreVehicleController.php#L140-L149",
                "x-route-name": "store.garage.destroy",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "CustomerVehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Garage vehicle id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not signed in."
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/online_store/garage/{id}/select": {
            "post": {
                "operationId": "post_online_store_garage_id_select",
                "tags": [
                    "My Garage"
                ],
                "summary": "Activate a garage vehicle",
                "description": "Makes it the default and the current session vehicle.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreVehicleController@selectGarage",
                "x-source": "app/Http/Controllers/StoreVehicleController.php#L115-L137",
                "x-route-name": "store.garage.select",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "CustomerVehicle"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Garage vehicle id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `vehicle`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "vehicle": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not signed in."
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/lang/{locale}": {
            "get": {
                "operationId": "get_online_store_lang_locale",
                "tags": [
                    "Storefront Pages & Search"
                ],
                "summary": "Switch storefront language",
                "description": "Stores the locale in the session / cookie and redirects back.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-route-name": "lang.switch",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "parameters": [
                    {
                        "name": "locale",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "en"
                        },
                        "description": "Locale code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/online_store/login": {
            "get": {
                "operationId": "get_online_store_login",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Login page (HTML)",
                "description": "Renders the shopper login form.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@showLogin",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L43-L49",
                "x-route-name": "store.login.show",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "guest:store"
                ],
                "x-models": [
                    "StoreSetting"
                ],
                "x-response-type": "html",
                "parameters": [
                    {
                        "name": "redirect",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Path to return to after login (same-site only)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "post_online_store_login",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Sign in",
                "description": "Authenticates a shopper and starts the store session. Blocked and unverified accounts (when verification is required) are refused with a form error. Redirects to `redirect` or the account page.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@login",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L52-L101",
                "x-route-name": "store.login",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "guest:store"
                ],
                "x-models": [
                    "StoreSetting",
                    "EcommerceClient"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email."
                                    },
                                    "password": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Password."
                                    },
                                    "redirect": {
                                        "type": "string",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Return path."
                                    },
                                    "remember": {
                                        "type": "boolean",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "boolean"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Keep me signed in."
                                    }
                                },
                                "required": [
                                    "email",
                                    "password"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "302": {
                        "description": "Redirect on success or back with errors."
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/logout": {
            "post": {
                "operationId": "post_online_store_logout",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Sign out",
                "description": "Ends the store session and redirects to the login page.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "StoreAuthController@logout",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L383-L391",
                "x-route-name": "store.logout",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-may-redirect": true,
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/loyalty": {
            "get": {
                "operationId": "get_online_store_my_loyalty",
                "tags": [
                    "My Loyalty Points"
                ],
                "summary": "My loyalty summary",
                "description": "Points balance + redeemable rewards + recent activity for the logged-in storefront customer. /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerLoyaltyController@summary",
                "x-source": "app/Http/Controllers/Api/Store/CustomerLoyaltyController.php#L26-L57",
                "x-route-name": "my_loyalty.summary",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "Client",
                    "LoyaltyPointTransaction",
                    "StoreSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`points`, `eligible`, `currency`, redeemable `rewards[]`, recent `transactions`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "points": {
                                            "type": "number"
                                        },
                                        "eligible": {
                                            "type": "boolean"
                                        },
                                        "currency": {
                                            "type": "string"
                                        },
                                        "rewards": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "transactions": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/loyalty/redeem": {
            "post": {
                "operationId": "post_online_store_my_loyalty_redeem",
                "tags": [
                    "My Loyalty Points"
                ],
                "summary": "Redeem a reward",
                "description": "Spends points for a reward; returns the generated `code` (coupon / voucher) when applicable.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerLoyaltyController@redeem",
                "x-source": "app/Http/Controllers/Api/Store/CustomerLoyaltyController.php#L59-L84",
                "x-route-name": "my_loyalty.redeem",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "LoyaltyReward"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reward_id": {
                                        "type": "integer",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reward id."
                                    }
                                },
                                "required": [
                                    "reward_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `reward_type`, `code`, remaining `points`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "reward_type": {},
                                        "code": {},
                                        "points": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "description": "Reward unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/loyalty/redemptions": {
            "get": {
                "operationId": "get_online_store_my_loyalty_redemptions",
                "tags": [
                    "My Loyalty Points"
                ],
                "summary": "My reward redemptions",
                "description": "The shopper's reward redemptions with points spent, reward, order and date.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerLoyaltyController@redemptions",
                "x-source": "app/Http/Controllers/Api/Store/CustomerLoyaltyController.php#L86-L106",
                "x-route-name": "my_loyalty.redemptions",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "LoyaltyRewardRedemption"
                ],
                "responses": {
                    "200": {
                        "description": "`data[] {id, reward_name, reward_type, points_spent, status, code, created_at}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/orders": {
            "get": {
                "operationId": "get_online_store_my_orders",
                "tags": [
                    "My Orders"
                ],
                "summary": "List my orders",
                "description": "GET /store/my/orders Query: page, per_page, q (ref), status (pending|confirmed|cancelled), from, to, sort, dir /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\MyOrdersApiController@index",
                "x-source": "app/Http/Controllers/Api/Store/MyOrdersApiController.php#L16-L66",
                "x-route-name": "my_orders.index",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-paginated": true,
                "x-models": [
                    "OnlineOrder"
                ],
                "parameters": [
                    {
                        "name": "dir",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`asc` / `desc`."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date from."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 10)."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Order ref."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`created_at`, `total`, `ref`, `date`."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`pending`, `confirmed`, `shipped`, `delivered`, `cancelled`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "format": "date",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Date to."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[] {id, code, status, total, payment_method, payment_status, created_at, warehouse_name}` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "code": {},
                                        "status": {},
                                        "total": {
                                            "type": "number"
                                        },
                                        "payment_method": {},
                                        "payment_status": {},
                                        "created_at": {
                                            "type": "string"
                                        },
                                        "warehouse_name": {},
                                        "data": {
                                            "type": "integer"
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/orders/{id}": {
            "get": {
                "operationId": "get_online_store_my_orders_id",
                "tags": [
                    "My Orders"
                ],
                "summary": "Get one of my orders",
                "description": "Header, shipping details, totals, `payment_instructions` for manual methods, `payment_proofs[]`, `can_submit_proof` and `items[]`. Orders of other customers return `404`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\MyOrdersApiController@show",
                "x-source": "app/Http/Controllers/Api/Store/MyOrdersApiController.php#L72-L166",
                "x-route-name": "my_orders.show",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Order object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "code": {},
                                        "status": {},
                                        "date": {},
                                        "time": {},
                                        "warehouse_id": {},
                                        "warehouse_name": {},
                                        "customer_name": {},
                                        "customer_email": {},
                                        "customer_phone": {},
                                        "shipping_address": {},
                                        "shipping_city": {},
                                        "shipping_state": {},
                                        "shipping_zip": {},
                                        "shipping_country": {},
                                        "subtotal": {
                                            "type": "integer"
                                        },
                                        "tax": {
                                            "type": "number"
                                        },
                                        "tax_rate": {
                                            "type": "number"
                                        },
                                        "shipping": {
                                            "type": "number"
                                        },
                                        "shipping_method_name": {},
                                        "discount": {
                                            "type": "number",
                                            "example": 0
                                        },
                                        "total": {
                                            "type": "number"
                                        },
                                        "payment_method": {},
                                        "payment_status": {},
                                        "delivery_method": {},
                                        "pickup_branch": {},
                                        "payment_instructions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "payment_proofs": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "can_submit_proof": {},
                                        "items": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "product_id": {},
                                        "product_variant_id": {},
                                        "name": {
                                            "type": "string"
                                        },
                                        "qty": {
                                            "type": "number"
                                        },
                                        "price": {
                                            "type": "number"
                                        },
                                        "line_total": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/orders/{id}/payment-proofs": {
            "get": {
                "operationId": "get_online_store_my_orders_id_payment_proofs",
                "tags": [
                    "My Orders"
                ],
                "summary": "Payment proofs of an order",
                "description": "Current `payment_status`, whether a new proof `can_submit`, the payment `instructions` (account details) and the submitted `proofs`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\PaymentProofController@index",
                "x-source": "app/Http/Controllers/Api/Store/PaymentProofController.php#L28-L39",
                "x-route-name": "my_orders.proofs.index",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "payment_method": {},
                                        "payment_status": {},
                                        "can_submit": {},
                                        "instructions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "proofs": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            },
            "post": {
                "operationId": "post_online_store_my_orders_id_payment_proofs",
                "tags": [
                    "My Orders"
                ],
                "summary": "Submit a payment proof",
                "description": "Multipart. Only for `gcash` / `bank_transfer` orders that are unpaid, not cancelled and have no proof pending review. Rate-limited (10/min).",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\PaymentProofController@store",
                "x-source": "app/Http/Controllers/Api/Store/PaymentProofController.php#L42-L95",
                "x-route-name": "my_orders.proofs.store",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store",
                    "throttle:10,1"
                ],
                "x-rate-limit": {
                    "requests": 10,
                    "per_minutes": 1
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Order id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Amount paid."
                                    },
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "x-format": "mimes:jpg,jpeg,png,webp,pdf",
                                        "maxLength": 5120,
                                        "x-laravel-rules": [
                                            "required",
                                            "file",
                                            "mimes:jpg,jpeg,png,webp,pdf",
                                            "max:5120"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "file"
                                        ],
                                        "description": "Screenshot / receipt (jpg, png, webp, pdf; max 5 MB)."
                                    },
                                    "note": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:500"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Note."
                                    },
                                    "paid_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "date"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Payment date."
                                    },
                                    "reference_number": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Transaction reference."
                                    }
                                },
                                "required": [
                                    "amount",
                                    "file",
                                    "reference_number"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "x-multipart": true,
                "responses": {
                    "201": {
                        "description": "`success`, `proof`, `can_submit: false`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "proof": {},
                                        "can_submit": {
                                            "type": "boolean",
                                            "example": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/returns": {
            "get": {
                "operationId": "get_online_store_my_returns",
                "tags": [
                    "My Returns"
                ],
                "summary": "My return & cancellation requests",
                "description": "GET /my/returns — all of the customer's return & cancellation requests.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerReturnsController@myReturns",
                "x-source": "app/Http/Controllers/Api/Store/CustomerReturnsController.php#L31-L59",
                "x-route-name": "my_returns.index",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "OnlineOrderReturn"
                ],
                "responses": {
                    "200": {
                        "description": "`data[] {id, order_id, order_ref, type, status, reason, refund_amount, items_count, created_at, refunded_at}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "order_id": {},
                                        "order_ref": {},
                                        "type": {},
                                        "status": {},
                                        "reason": {},
                                        "refund_amount": {
                                            "type": "number"
                                        },
                                        "items_count": {
                                            "type": "integer"
                                        },
                                        "created_at": {
                                            "type": "string"
                                        },
                                        "refunded_at": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/wallet": {
            "get": {
                "operationId": "get_online_store_my_wallet",
                "tags": [
                    "My Wallet"
                ],
                "summary": "My wallet summary",
                "description": "Wallet balance + recent activity + withdrawal config for the logged-in storefront customer. Returns 403 if the E-Wallet feature is off. /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerWalletController@summary",
                "x-source": "app/Http/Controllers/Api/Store/CustomerWalletController.php#L25-L60",
                "x-route-name": "my_wallet.summary",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "WalletWithdrawal",
                    "StoreSetting"
                ],
                "responses": {
                    "200": {
                        "description": "`balance`, `currency`, `status`, `withdrawal_enabled`, `min_withdrawal`, last 10 `transactions`, `pending_withdrawals`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "balance": {
                                            "type": "number"
                                        },
                                        "currency": {
                                            "type": "string"
                                        },
                                        "status": {},
                                        "withdrawal_enabled": {
                                            "type": "boolean"
                                        },
                                        "min_withdrawal": {
                                            "type": "number"
                                        },
                                        "transactions": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "pending_withdrawals": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Wallet disabled."
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/wallet/redeem": {
            "post": {
                "operationId": "post_online_store_my_wallet_redeem",
                "tags": [
                    "My Wallet"
                ],
                "summary": "Redeem a gift card / voucher code",
                "description": "Redeem a gift-card / wallet-item code into the customer's balance. /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerWalletController@redeem",
                "x-source": "app/Http/Controllers/Api/Store/CustomerWalletController.php#L87-L107",
                "x-route-name": "my_wallet.redeem",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Card code."
                                    }
                                },
                                "required": [
                                    "code"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `credited`, new `balance`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "credited": {
                                            "type": "number"
                                        },
                                        "balance": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/wallet/transactions": {
            "get": {
                "operationId": "get_online_store_my_wallet_transactions",
                "tags": [
                    "My Wallet"
                ],
                "summary": "My wallet transactions",
                "description": "The shopper's wallet ledger: credits (refunds, top-ups), debits (orders, withdrawals), balance after each entry.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerWalletController@transactions",
                "x-source": "app/Http/Controllers/Api/Store/CustomerWalletController.php#L62-L82",
                "x-route-name": "my_wallet.transactions",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-paginated": true,
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "integer"
                        },
                        "description": "Page size (default 15)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`data[]` and `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "meta": {
                                            "type": "object",
                                            "properties": {
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "pages": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/my/wallet/withdraw": {
            "post": {
                "operationId": "post_online_store_my_wallet_withdraw",
                "tags": [
                    "My Wallet"
                ],
                "summary": "Request a withdrawal",
                "description": "Held as `pending` until an admin approves. Refused when withdrawals are disabled, below the minimum, or above the balance.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerWalletController@withdraw",
                "x-source": "app/Http/Controllers/Api/Store/CustomerWalletController.php#L112-L158",
                "x-route-name": "my_wallet.withdraw",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store"
                ],
                "x-models": [
                    "StoreSetting",
                    "WalletWithdrawal"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number",
                                        "minimum": 0.01,
                                        "x-laravel-rules": [
                                            "required",
                                            "numeric",
                                            "min:0.01"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Amount."
                                    },
                                    "destination": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account / number to pay to."
                                    },
                                    "method": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Payout method (e.g. `bank`, `gcash`)."
                                    }
                                },
                                "required": [
                                    "amount"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`success` and `id`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "id": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/newsletter/subscribe": {
            "post": {
                "operationId": "post_online_store_newsletter_subscribe",
                "tags": [
                    "Newsletter"
                ],
                "summary": "Subscribe to the newsletter",
                "description": "Adds the email to the newsletter list (double opt-in when enabled). Public; rate-limited.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\NewsletterController@subscribe",
                "x-source": "app/Http/Controllers/Api/Store/NewsletterController.php#L11-L24",
                "x-route-name": "newsletter.subscribe",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "Subscriber"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "x-unique": "subscribers,email",
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "max:190",
                                            "unique:subscribers,email"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email (unique)."
                                    }
                                },
                                "required": [
                                    "email"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`success`, `message`, `subscriber`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string"
                                        },
                                        "subscriber": {}
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/products/{id}/questions": {
            "get": {
                "operationId": "get_online_store_products_id_questions",
                "tags": [
                    "Reviews & Questions"
                ],
                "summary": "Published Q&A of a product (public)",
                "description": "GET /products/{id}/questions — published Q&A, readable by anyone.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CustomerQuestionsController@productQuestions",
                "x-source": "app/Http/Controllers/Api/Store/CustomerQuestionsController.php#L20-L43",
                "x-route-name": "store.product.questions",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "ProductQuestion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`count`, `can_ask`, `questions[] {id, asker_name, question, answer, asked_at, answered_at, is_mine}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        },
                                        "can_ask": {
                                            "type": "boolean"
                                        },
                                        "questions": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "post_online_store_products_id_questions",
                "tags": [
                    "Reviews & Questions"
                ],
                "summary": "Ask a question",
                "description": "Signed-in shoppers only; rate-limited (10/min) and capped on unanswered questions per product.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-controller": "Api\\Store\\CustomerQuestionsController@ask",
                "x-source": "app/Http/Controllers/Api/Store/CustomerQuestionsController.php#L46-L87",
                "x-route-name": "store.product.questions.ask",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "auth:store",
                    "throttle:10,1"
                ],
                "x-rate-limit": {
                    "requests": 10,
                    "per_minutes": 1
                },
                "x-models": [
                    "Product",
                    "ProductQuestion"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "question": {
                                        "type": "string",
                                        "minLength": 5,
                                        "maxLength": 1000,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "min:5",
                                            "max:1000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Question text (5–1000 chars)."
                                    }
                                },
                                "required": [
                                    "question"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "429": {
                        "description": "Too many pending questions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "StoreSession": []
                    }
                ]
            }
        },
        "/online_store/products/{id}/reviews": {
            "get": {
                "operationId": "get_online_store_products_id_reviews",
                "tags": [
                    "Reviews & Questions"
                ],
                "summary": "Approved reviews of a product (public)",
                "description": "GET /products/{id}/reviews — public: approved reviews + average.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CustomerReviewsController@productReviews",
                "x-source": "app/Http/Controllers/Api/Store/CustomerReviewsController.php#L110-L128",
                "x-route-name": "store.product.reviews",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "ProductReview"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`count`, `average`, `reviews[] {name, rating, comment, date}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "count": {
                                            "type": "integer"
                                        },
                                        "average": {
                                            "type": "number"
                                        },
                                        "reviews": {
                                            "type": "array",
                                            "items": {}
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/online_store/properties/inquiry": {
            "post": {
                "operationId": "post_online_store_properties_inquiry",
                "tags": [
                    "Property Listings"
                ],
                "summary": "Send a property inquiry",
                "description": "Stores the inquiry (`status = new`) and notifies the agent / admin. `company` is a honeypot.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "RealEstateStoreController@inquiry",
                "x-source": "app/Http/Controllers/RealEstateStoreController.php#L193-L221",
                "x-route-name": "store.realestate.inquiry",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "PropertyInquiry"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "company": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Honeypot — leave empty."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "email",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email."
                                    },
                                    "message": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Message."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 50,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:50"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    },
                                    "property_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-exists": "properties,id",
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer",
                                            "exists:properties,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Listing id."
                                    }
                                },
                                "required": [
                                    "message",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/quote-request": {
            "post": {
                "operationId": "post_online_store_quote_request",
                "tags": [
                    "Quote Requests"
                ],
                "summary": "Submit a quote request (public)",
                "description": "Rate-limited to 8 requests per minute. Linked to the logged-in shopper when any.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\QuoteRequestsController@store",
                "x-source": "app/Http/Controllers/Api/Store/QuoteRequestsController.php#L19-L55",
                "x-route-name": "store.quote.request",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "throttle:8,1"
                ],
                "x-rate-limit": {
                    "requests": 8,
                    "per_minutes": 1
                },
                "x-models": [
                    "Product",
                    "StoreQuoteRequest"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email."
                                    },
                                    "message": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:2000"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Message."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Name."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    },
                                    "product_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product."
                                    },
                                    "quantity": {
                                        "type": "number",
                                        "minimum": 0,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "numeric",
                                            "min:0"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Requested quantity."
                                    }
                                },
                                "required": [
                                    "email",
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "`success` and `message`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/register": {
            "get": {
                "operationId": "get_online_store_register",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Registration page (HTML)",
                "description": "GET /store/register",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@showRegister",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L104-L115",
                "x-route-name": "store.register.show",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "guest:store"
                ],
                "x-models": [
                    "StoreSetting"
                ],
                "x-response-type": "html",
                "parameters": [
                    {
                        "name": "redirect",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Return path."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "post_online_store_register",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Register a shopper account",
                "description": "Creates a `Client` and its store login. Refused when registration is disabled. `invite_code` is required only when the store requires invite codes. Depending on settings the account then needs email verification (`require_email_verification`) and/or admin approval (`require_admin_approval`, account `status = 0` until approved).",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@register",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L118-L213",
                "x-route-name": "store.register",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "guest:store"
                ],
                "x-models": [
                    "StoreSetting",
                    "InviteCode",
                    "Client",
                    "EcommerceClient"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "address": {
                                        "type": "string",
                                        "maxLength": 190,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:190"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Address."
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 190,
                                        "x-unique": "ecommerce_clients,email ->whereNull",
                                        "x-laravel-rules": [
                                            "required",
                                            "email",
                                            "max:190",
                                            "unique:clients,email ->whereNull",
                                            "unique:ecommerce_clients,email ->whereNull"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Email (unique among clients and store accounts)."
                                    },
                                    "invite_code": {
                                        "type": "string",
                                        "maxLength": 64,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:64"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Invite code (when required)."
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:120"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Full name."
                                    },
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "minLength": 8,
                                        "x-rules": [
                                            "confirmed (send <field>_confirmation)"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "confirmed",
                                            "min:8 ->mixedCase->numbers->symbols"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "except"
                                        ],
                                        "description": "Password (min 8, mixed case, number, symbol)."
                                    },
                                    "password_confirmation": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "except"
                                        ],
                                        "description": "Repeat password."
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 30,
                                        "x-laravel-rules": [
                                            "required",
                                            "string",
                                            "max:30"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Phone."
                                    },
                                    "redirect": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Return path."
                                    },
                                    "terms": {
                                        "type": "boolean",
                                        "x-rules": [
                                            "accepted (must be true)"
                                        ],
                                        "x-laravel-rules": [
                                            "accepted"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Must be accepted."
                                    }
                                },
                                "required": [
                                    "address",
                                    "email",
                                    "invite_code",
                                    "name",
                                    "password",
                                    "phone"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "302": {
                        "description": "Redirect to login (verify / pending approval) or account."
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/reset-password": {
            "post": {
                "operationId": "post_online_store_reset_password",
                "tags": [
                    "Customer Authentication"
                ],
                "summary": "Reset the password",
                "description": "Rate-limited (5/min). Consumes the token from the reset email.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreAuthController@resetPassword",
                "x-source": "app/Http/Controllers/StoreAuthController.php#L326-L362",
                "x-route-name": "store.password.update",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale",
                    "guest:store",
                    "throttle:5,1"
                ],
                "x-rate-limit": {
                    "requests": 5,
                    "per_minutes": 1
                },
                "x-models": [
                    "EcommerceClient"
                ],
                "x-may-redirect": true,
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "x-laravel-rules": [
                                            "required",
                                            "email"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Account email."
                                    },
                                    "password": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "minLength": 8,
                                        "x-rules": [
                                            "confirmed (send <field>_confirmation)"
                                        ],
                                        "x-laravel-rules": [
                                            "required",
                                            "confirmed",
                                            "min:8 ->mixedCase->numbers->symbols"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "New password (min 8, mixed case, number, symbol)."
                                    },
                                    "token": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Reset token."
                                    }
                                },
                                "required": [
                                    "email",
                                    "password",
                                    "token"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/search/suggestions": {
            "get": {
                "operationId": "get_online_store_search_suggestions",
                "tags": [
                    "Storefront Pages & Search"
                ],
                "summary": "Search autocomplete",
                "description": "Up to 8 matching products (name, code or note), filtered by the selected vehicle when fitment is on. Returns `[]` for queries shorter than 2 chars.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreFrontController@searchSuggestions",
                "x-source": "app/Http/Controllers/StoreFrontController.php#L1515-L1544",
                "x-route-name": "store.search.suggestions",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search text."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of `{id, name, code, image_url, price, …}`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {}
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/shop": {
            "get": {
                "operationId": "get_online_store_shop",
                "tags": [
                    "Storefront Pages & Search"
                ],
                "summary": "Shop page (HTML)",
                "description": "Product listing with filters; prices sort on the effective base price.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreFrontController@shop",
                "x-source": "app/Http/Controllers/StoreFrontController.php#L447-L617",
                "x-route-name": "store.shop",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-paginated": true,
                "x-models": [
                    "StoreSetting",
                    "Product",
                    "Category",
                    "Collection"
                ],
                "x-response-type": "html",
                "parameters": [
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Category id."
                    },
                    {
                        "name": "collection",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Collection id or slug."
                    },
                    {
                        "name": "max",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Max price."
                    },
                    {
                        "name": "min",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Min price."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Search."
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "`latest`, `price_asc`, `price_desc`."
                    },
                    {
                        "name": "sub_category",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Sub-category id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/online_store/store/checkout-quote": {
            "post": {
                "operationId": "post_online_store_store_checkout_quote",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "Quote the cart",
                "description": "Server-side pricing for the checkout page: subtotal, coupon discount (with `coupon_error` when invalid), tax (destination-based), shipping cost, total and the `shipping_methods` available for the destination. Requires a store session (`401` otherwise).",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@quote",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L64-L160",
                "x-route-name": "store.checkout.quote",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "Client",
                    "Warehouse"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Destination country (defaults to the client's)."
                                    },
                                    "coupon_code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Coupon."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "product_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product."
                                                },
                                                "product_variant_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Variant."
                                                },
                                                "qty": {
                                                    "type": "number",
                                                    "minimum": 1,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "numeric",
                                                        "min:1"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity."
                                                }
                                            },
                                            "required": [
                                                "product_id",
                                                "qty"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Cart lines."
                                    },
                                    "payment_method": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Payment method key (pickup methods skip shipping)."
                                    },
                                    "pickup_branch_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Pickup branch."
                                    },
                                    "shipping_method_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated",
                                            "read"
                                        ],
                                        "description": "Chosen shipping rate."
                                    },
                                    "state": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Destination state."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Fulfilment warehouse."
                                    }
                                },
                                "required": [
                                    "items"
                                ]
                            },
                            "example": {
                                "items": [
                                    {
                                        "product_id": 120,
                                        "qty": 2
                                    }
                                ],
                                "shipping_method_id": 3,
                                "coupon_code": "WELCOME10",
                                "payment_method": "cod",
                                "country": "Morocco"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Quote object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "subtotal": {
                                            "type": "integer"
                                        },
                                        "discount": {
                                            "type": "integer"
                                        },
                                        "coupon_code": {
                                            "type": "string"
                                        },
                                        "coupon_error": {},
                                        "tax": {},
                                        "tax_rate": {},
                                        "shipping_cost": {},
                                        "total": {
                                            "type": "number"
                                        },
                                        "shipping_methods": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "shipping_required": {},
                                        "is_pickup": {},
                                        "country": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Unauthenticated"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/store/flutterwave/return": {
            "get": {
                "operationId": "get_online_store_store_flutterwave_return",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "Flutterwave return URL",
                "description": "Verifies `tx_ref` against the Flutterwave API before marking paid; `status=cancelled` cancels the order.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@flutterwaveReturn",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L857-L900",
                "x-route-name": "store.flutterwave.return",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Redirect status."
                    },
                    {
                        "name": "tx_ref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Transaction reference."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/online_store/store/orders": {
            "post": {
                "operationId": "post_online_store_store_orders",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "Place an order",
                "description": "Validates stock (unless overselling is allowed), applies the coupon, recomputes totals and creates the online order (`pending`). Behaviour by method: Stripe requires a succeeded `stripe_payment_intent_id`; `wallet` debits the wallet immediately; redirect gateways return an `approve_url` to send the shopper to; `gcash` / `bank_transfer` return payment instructions and expect a proof; `cod`, `mobile_money`, `cash_on_pickup` are pay-later. Loyalty points and confirmation emails are handled after payment.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@store",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L243-L743",
                "x-route-name": "store.orders.store",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "StoreSetting",
                    "StorePickupBranch",
                    "Client",
                    "OnlineOrder",
                    "StoreCouponRedemption",
                    "StoreCoupon"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "coupon_code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Coupon."
                                    },
                                    "customer_name": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:150"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Recipient name."
                                    },
                                    "customer_phone": {
                                        "type": "string",
                                        "maxLength": 40,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:40"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Recipient phone."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "product_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product."
                                                },
                                                "product_variant_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Variant."
                                                },
                                                "qty": {
                                                    "type": "number",
                                                    "minimum": 1,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "numeric",
                                                        "min:1"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity."
                                                }
                                            },
                                            "required": [
                                                "product_id",
                                                "qty"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Cart lines."
                                    },
                                    "payment_method": {
                                        "type": "string",
                                        "x-laravel-rules": [
                                            "required",
                                            "string"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "One of the enabled methods (see tag description)."
                                    },
                                    "pickup_branch_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Required for `cash_on_pickup`."
                                    },
                                    "shipping_address": {
                                        "type": "string",
                                        "maxLength": 250,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:250"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Street."
                                    },
                                    "shipping_city": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "City."
                                    },
                                    "shipping_country": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Country."
                                    },
                                    "shipping_method_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Shipping rate."
                                    },
                                    "shipping_state": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:100"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "State."
                                    },
                                    "shipping_zip": {
                                        "type": "string",
                                        "maxLength": 30,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:30"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Postal code."
                                    },
                                    "stripe_payment_intent_id": {
                                        "type": "string",
                                        "maxLength": 128,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:128"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Stripe intent (credit_card)."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse."
                                    }
                                },
                                "required": [
                                    "items",
                                    "payment_method"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "product_id": {},
                                        "product_variant_id": {},
                                        "qty": {},
                                        "price": {},
                                        "line_total": {},
                                        "TaxNet": {},
                                        "discount": {},
                                        "discount_method": {},
                                        "tax_method": {},
                                        "is_preorder": {},
                                        "created_at": {
                                            "type": "string"
                                        },
                                        "updated_at": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "201": {
                        "description": "`id`, `ref`, `status`, totals, `payment_method`, `payment_status`, and `approve_url` for redirect gateways.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {},
                                        "ref": {},
                                        "status": {},
                                        "date": {
                                            "type": "string"
                                        },
                                        "time": {
                                            "type": "string"
                                        },
                                        "subtotal": {
                                            "type": "number"
                                        },
                                        "discount": {
                                            "type": "number"
                                        },
                                        "coupon_code": {},
                                        "tax": {
                                            "type": "number"
                                        },
                                        "shipping_cost": {
                                            "type": "number"
                                        },
                                        "total": {
                                            "type": "number"
                                        },
                                        "payment_method": {},
                                        "payment_status": {},
                                        "approve_url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Unauthenticated"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Out of stock / coupon conflict.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "502": {
                        "description": "Gateway error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/store/payment-intent": {
            "post": {
                "operationId": "post_online_store_store_payment_intent",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "Create a Stripe PaymentIntent",
                "description": "Creates the intent for the server-computed total; the returned `clientSecret` is confirmed by Stripe.js, then the order is placed with `stripe_payment_intent_id`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@createPaymentIntent",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L166-L241",
                "x-route-name": "store.payment.intent",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "StoreSetting",
                    "Client"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "country": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Country."
                                    },
                                    "coupon_code": {
                                        "type": "string",
                                        "maxLength": 60,
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "string",
                                            "max:60"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Coupon."
                                    },
                                    "items": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "product_id": {
                                                    "type": "integer",
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Product ID of the cart line."
                                                },
                                                "product_variant_id": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "x-laravel-rules": [
                                                        "nullable",
                                                        "integer"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Variant ID, or `null` for products without variants."
                                                },
                                                "qty": {
                                                    "type": "number",
                                                    "minimum": 1,
                                                    "x-laravel-rules": [
                                                        "required",
                                                        "numeric",
                                                        "min:1"
                                                    ],
                                                    "x-sources": [
                                                        "validated"
                                                    ],
                                                    "description": "Quantity ordered."
                                                }
                                            },
                                            "required": [
                                                "product_id",
                                                "qty"
                                            ]
                                        },
                                        "minItems": 1,
                                        "x-laravel-rules": [
                                            "required",
                                            "array",
                                            "min:1"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Cart lines."
                                    },
                                    "shipping_method_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Shipping rate."
                                    },
                                    "state": {
                                        "x-inferred": true,
                                        "type": "string",
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "State."
                                    },
                                    "warehouse_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "x-laravel-rules": [
                                            "nullable",
                                            "integer"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Warehouse."
                                    }
                                },
                                "required": [
                                    "items"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`clientSecret`, `amount`, `subtotal`, `tax`, `shipping_cost`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "clientSecret": {},
                                        "amount": {},
                                        "subtotal": {},
                                        "tax": {},
                                        "shipping_cost": {}
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Unauthenticated"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    },
                    "500": {
                        "description": "Stripe not configured.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/store/paypal/cancel": {
            "get": {
                "operationId": "get_online_store_store_paypal_cancel",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "PayPal cancel URL",
                "description": "Cancels the pending order and redirects to checkout.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@paypalCancel",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L792-L802",
                "x-route-name": "store.paypal.cancel",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "PayPal order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/online_store/store/paypal/return": {
            "get": {
                "operationId": "get_online_store_store_paypal_return",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "PayPal return URL",
                "description": "Captures the approved PayPal order, marks the online order paid and redirects to the thank-you page (or back to checkout on failure). Idempotent.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@paypalReturn",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L751-L785",
                "x-route-name": "store.paypal.return",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "PayPal order id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/online_store/store/paystack/return": {
            "get": {
                "operationId": "get_online_store_store_paystack_return",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "Paystack callback URL",
                "description": "Verifies the transaction with Paystack before marking the order paid.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@paystackReturn",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L811-L849",
                "x-route-name": "store.paystack.return",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "reference",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Paystack reference."
                    },
                    {
                        "name": "trxref",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Alternative reference param."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/online_store/store/razorpay/return": {
            "get": {
                "operationId": "get_online_store_store_razorpay_return",
                "tags": [
                    "Checkout & Payments"
                ],
                "summary": "Razorpay callback URL",
                "description": "Fetches the payment link and requires status `paid`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "Api\\Store\\CheckoutController@razorpayReturn",
                "x-source": "app/Http/Controllers/Api/Store/CheckoutController.php#L908-L946",
                "x-route-name": "store.razorpay.return",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "OnlineOrder"
                ],
                "x-may-redirect": true,
                "parameters": [
                    {
                        "name": "razorpay_payment_link_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-sources": [
                                "read"
                            ],
                            "type": "string"
                        },
                        "description": "Payment link id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                },
                "security": []
            }
        },
        "/online_store/vehicle": {
            "post": {
                "operationId": "post_online_store_vehicle",
                "tags": [
                    "My Garage"
                ],
                "summary": "Select a vehicle",
                "description": "Stores the vehicle in the session; logged-in customers also get it saved to their garage unless `save=false`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreVehicleController@select",
                "x-source": "app/Http/Controllers/StoreVehicleController.php#L71-L103",
                "x-route-name": "store.vehicle.select",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-accepts-all-input": true,
                "x-models": [
                    "CustomerVehicle"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "save": {
                                        "x-sources": [
                                            "read"
                                        ],
                                        "description": "Save to garage (default true).",
                                        "type": "boolean"
                                    },
                                    "make_id": {
                                        "type": "integer",
                                        "description": "Vehicle make.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "model_id": {
                                        "type": "integer",
                                        "description": "Vehicle model.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "year": {
                                        "type": "integer",
                                        "description": "Model year.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    },
                                    "engine": {
                                        "type": "string",
                                        "description": "Engine / trim.",
                                        "x-sources": [
                                            "documented"
                                        ]
                                    }
                                },
                                "additionalProperties": true,
                                "x-accepts-all-input": true,
                                "required": [
                                    "make_id",
                                    "model_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`ok` and normalised `vehicle`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "vehicle": {}
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Make/model missing.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/vehicle/clear": {
            "post": {
                "operationId": "post_online_store_vehicle_clear",
                "tags": [
                    "My Garage"
                ],
                "summary": "Clear the selected vehicle",
                "description": "POST /vehicle/clear — browse without a vehicle again.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreVehicleController@clear",
                "x-source": "app/Http/Controllers/StoreVehicleController.php#L106-L112",
                "x-route-name": "store.vehicle.clear",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "responses": {
                    "200": {
                        "description": "`{ \"ok\": true }`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/vehicle/options": {
            "get": {
                "operationId": "get_online_store_vehicle_options",
                "tags": [
                    "My Garage"
                ],
                "summary": "Vehicle picker options",
                "description": "Active `makes` and `models`, the `current` session vehicle, the customer's `garage` and `logged_in`.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreVehicleController@options",
                "x-source": "app/Http/Controllers/StoreVehicleController.php#L38-L68",
                "x-route-name": "store.vehicle.options",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "CustomerVehicle",
                    "VehicleMake",
                    "VehicleModel"
                ],
                "responses": {
                    "200": {
                        "description": "Options object.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "makes": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "models": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "current": {},
                                        "garage": {},
                                        "logged_in": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/wholesale-tiers": {
            "get": {
                "operationId": "get_online_store_wholesale_tiers",
                "tags": [
                    "Storefront Pages & Search"
                ],
                "summary": "Wholesale quantity tiers",
                "description": "Quantity-break prices for the products in the cart, so the cart can re-price live. `enabled: false` when wholesale pricing is off.",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "StoreFrontController@wholesaleTiers",
                "x-source": "app/Http/Controllers/StoreFrontController.php#L861-L895",
                "x-route-name": "store.wholesale.tiers",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "StoreSetting",
                    "Product"
                ],
                "parameters": [
                    {
                        "name": "ids",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "x-inferred": true,
                            "type": "string",
                            "x-sources": [
                                "read"
                            ]
                        },
                        "description": "Comma-separated product ids (max 200)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`enabled` and `tiers` keyed by product id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "enabled": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "tiers": {}
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/wishlist/ids": {
            "get": {
                "operationId": "get_online_store_wishlist_ids",
                "tags": [
                    "Wishlist"
                ],
                "summary": "My wishlisted product ids",
                "description": "The current customer's wishlisted product ids (empty for guests). Lets storefront cards reflect saved state without touching every controller. /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "WishlistController@ids",
                "x-source": "app/Http/Controllers/WishlistController.php#L52-L62",
                "x-route-name": "store.wishlist.ids",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "Wishlist"
                ],
                "responses": {
                    "200": {
                        "description": "`ids[]` and `count` (empty for guests).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ids": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/online_store/wishlist/toggle": {
            "post": {
                "operationId": "post_online_store_wishlist_toggle",
                "tags": [
                    "Wishlist"
                ],
                "summary": "Toggle a product in my wishlist",
                "description": "Toggle a product in the current customer's wishlist. Returns { in_wishlist: bool, count: int }. /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "WishlistController@toggle",
                "x-source": "app/Http/Controllers/WishlistController.php#L16-L46",
                "x-route-name": "store.wishlist.toggle",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "Wishlist"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "product_id": {
                                        "type": "integer",
                                        "x-exists": "products,id",
                                        "x-laravel-rules": [
                                            "required",
                                            "integer",
                                            "exists:products,id"
                                        ],
                                        "x-sources": [
                                            "validated"
                                        ],
                                        "description": "Product."
                                    }
                                },
                                "required": [
                                    "product_id"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "`in_wishlist` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "in_wishlist": {
                                            "type": "array",
                                            "items": {}
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not signed in.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                },
                "security": []
            }
        },
        "/online_store/wishlist/{productId}/remove": {
            "post": {
                "operationId": "post_online_store_wishlist_productId_remove",
                "tags": [
                    "Wishlist"
                ],
                "summary": "Remove a product from my wishlist",
                "description": "Remove a product from the wishlist (used by the wishlist page). /",
                "x-section": "Storefront",
                "x-surface": "storefront",
                "x-public": true,
                "x-controller": "WishlistController@remove",
                "x-source": "app/Http/Controllers/WishlistController.php#L67-L82",
                "x-route-name": "store.wishlist.remove",
                "x-middleware": [
                    "web",
                    "request.safety",
                    "store.enabled",
                    "store.locale"
                ],
                "x-models": [
                    "Wishlist"
                ],
                "parameters": [
                    {
                        "name": "productId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Product id."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`ok` and `count`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Not signed in.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        }
    },
    "components": {
        "securitySchemes": {
            "BearerToken": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT (Laravel Passport)",
                "description": "Personal access token issued by `POST /api/getAccessToken` (web/SPA) or `POST /api/mobile/login` (mobile). Send as `Authorization: Bearer <token>`."
            },
            "StockyCookie": {
                "type": "apiKey",
                "in": "cookie",
                "name": "Stocky_token",
                "description": "Same Passport token stored in the `Stocky_token` cookie set by the login endpoint; used automatically by the admin SPA."
            },
            "PortalSession": {
                "type": "apiKey",
                "in": "cookie",
                "name": "laravel_session",
                "description": "Session cookie for the client portal (`portal` guard). Obtain via `POST /api/portal/login`. Requires the CSRF token header (`X-XSRF-TOKEN`) on mutating requests."
            },
            "StoreSession": {
                "type": "apiKey",
                "in": "cookie",
                "name": "laravel_session",
                "description": "Session cookie for storefront customers (`store` guard). Obtain via the storefront login. Requires the CSRF token header on mutating requests."
            },
            "WebSession": {
                "type": "apiKey",
                "in": "cookie",
                "name": "laravel_session",
                "description": "Admin web session (`web` guard)."
            }
        },
        "parameters": {
            "limit": {
                "name": "limit",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "default": 10
                },
                "description": "Rows per page. Send `-1` (or omit) to return every row without pagination."
            },
            "page": {
                "name": "page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "default": 1,
                    "minimum": 1
                },
                "description": "Page number (1-based). Ignored when `limit` is `-1`."
            },
            "SortField": {
                "name": "SortField",
                "in": "query",
                "schema": {
                    "type": "string",
                    "default": "id"
                },
                "description": "Column to sort by. Must be a column of the underlying table."
            },
            "SortType": {
                "name": "SortType",
                "in": "query",
                "schema": {
                    "type": "string",
                    "enum": [
                        "asc",
                        "desc"
                    ],
                    "default": "desc"
                },
                "description": "Sort direction."
            },
            "search": {
                "name": "search",
                "in": "query",
                "schema": {
                    "type": "string"
                },
                "description": "Free-text search applied with `LIKE %term%` across the searchable columns of the resource."
            }
        },
        "responses": {
            "Unauthenticated": {
                "description": "Missing, expired or revoked token / session.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string",
                                    "example": "Unauthenticated."
                                }
                            }
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "The authenticated user lacks the required permission.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string",
                                    "example": "This action is unauthorized."
                                }
                            }
                        }
                    }
                }
            },
            "NotFound": {
                "description": "No record matches the given identifier.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string",
                                    "example": "No query results for model [App\\Models\\Client] 42"
                                }
                            }
                        }
                    }
                }
            },
            "ValidationError": {
                "description": "One or more request fields failed validation.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string",
                                    "example": "The given data was invalid."
                                },
                                "errors": {
                                    "type": "object",
                                    "additionalProperties": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "example": {
                                        "name": [
                                            "The name field is required."
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}